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ABSTRACT 


As  computer  software  becomes  increasingly  more  complex, 
the  need  for  an  adequate  and  widely  accepted  set  of  software 
design  principles  becomes  critical.  Traditionally,  the 
emphasis  in  computer  science  has  been  on  the  algorithm 
rather  than  on  good  software  design.  General  principles  for 
the  design  of  computer  software  are  very  important  but 
particularly  difficult  to  define,  and  discussion  of  general 
principles  is  almost  entirely  absent  from  the  literature. 
In  this  thesis,  general  principles  for  software  design  are 
discussed,  and  examples  of  their  influence  on  the  redesign 
of  a  graphical  subroutine  package  are  described. 
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CHAPTER  I 
INTRODUCTION 

The  project  dealt  with  in  this  thesis  included  the 
redesign  and  rewriting  of  a  moderately  complex  software 
system.  Although  this  redevelopment  consumed  a  major 
proportion  of  the  total  time  spent  on  the  project,  the 
description  of  the  software  itself  has  been  relegated  to 
examples  in  Chapter  III  and  the  Appendices.  The  author's 
chief  interest  lies  in  attempting  to  formulate  general 
principles  for  software  design.  Although  software  design  is 
in  many  respects  similar  to  hardware  design,  for  example  the 
need  for  extensibility  and  flexibility,  this  thesis  deals 
exclusively  with  software  design.  In  Chapter  II  of  this 
thesis,  several  aspects  of  software  design  are  explored  with 
illustrations  being  drawn  from  the  software  system  described 
in  Chapter  III  and  the  Appendices. 

Studies  on  principles  of  software  design  are  almost 
entirely  absent  from  the  literature.  There  are  many  books 
which,  from  their  titles,  would  appear  to  deal  with  software 
design  principles  and  technigues.  Upon  closer  examination 
however,  one  finds  articles  dealing  mainly  with  a  new  piece 
of  hardware  cr  software.  An  example  is  Software  Engineering 
(Tou  1970)  ,  a  two-volume  conference  proceedings  in  which 
most  articles  describe  new  hardware  and  software  systems. 

It  is  doubtful  whether  software  design  can  be 
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considered  a  science;  however,  software  design  is  very 
similar  to  many  areas  in  engineering,  that  is,  both  areas 
attempt  to  advance  the  current  level  of  technology. 
Engineers  have  developed  principles  for  highway  and  building 
construction,  and  it  should  be  possible  to  have  software 
engineers  formulate  software  engineering  principles. 


A  ma 
develop 
Although 
computer 
software 
research 
areas  as 
However , 
found  in 


jor  objective  for  many  computer  scientists  is  to 
effective  algorithms  to  solve  their  problems, 
the  problems  being  investigated  vary  greatly,  the 
scientists  have  in  common  the  need  fcr  well-written 
packages  for  problem  solving.  A  qreat  deal  of 
has  been  devoted  to  algorithm  development  in  such 
numerical  analysis  and  mathematical  programming, 
studies  on  software  design  principles  are  rarely 
the  literature. 


The  lack  of  adequate  software  results  in  much 
duplication  of  software  packages.  For  example,  a  compiler 
is  written,  but  due  to  a  lack  of  portability,  documentation, 
or  efficiency,  it  is  not  utilized  at  other  installations. 
Instead,  another  compiler  is  written,  probably  no  more 
competently  than  the  first  compiler.  Neumann  (1969) 
suggests  eleven  reasons  why  we  are  still  producing 
inadequate  software.  Among  these  reasons  he  mentions  the 
tendency  'to  repeat  the  mistakes  of  others'.  This 
duplication  of  development  and  resources  could  be  greatly 
reduced  if  more  emphasis  was  placed  on  software  design 
principles. 
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The  aspects  of  software  design  discussed  in  Chapter  II 

are : 


A) 

Modularity 

B) 

Standardization 

C) 

Efficiency  and 

Stability 

D) 

Flexibility  and 

Extensibility 

E) 

Documentation 

Following  the  general  discussion  in  Chapter  IIf  each  of 
the  points  is  re-examined  in  Chapter  III,  with  emphasis 
placed  on  the  effect  these  principles  have  had  on  the 
redesign  of  a  graphical  subroutine  package,  GFIDSUB  (Huen 
1969)  . 
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CHAPTER  II 

GENERAL  PRINCIPLES  CF  SOFTWARE  EES IGN 

2.0  Introduction 

This  chapter  formulates  general  principles  of  software 
design.  The  few  articles  that  exist  on  software  design 
principles  do  not  cover  these  principles  in  general,  but 
concentrate  cn  specific  aspects.  Fcr  example,  • How  To  Write 
Software  Specifications'  (Hartman  and  Owens  1967)  covers 
only  one  aspect  of  software  design,  as  the  title  implies. 

Hartman  and  Owens  aptly  describe  the  situation  in  their 
opening  paragraph:  'In  general,  computer  software  is  getting 
more  complicated  at  an  increasing  rate.  Unfortunately,  the 
people  who  develop  software  have  been  at  it  for  only  a 
relatively  shcrt  time.  The  result  is  predictable:  ever- 
larger  software  troubles.  This,  in  turn,  leads  many  people 
to  feel  insecure  about  software  development,  to  think  of  it 
as  a  modern  "black  art"  for  which  even  the  most  able 
practitioners  lose  the  recipe  every  few  months. ' 

Good  practices  in  design  of  software  are  very 
important,  but  hard  to  define.  This  chapter  is  not  intended 
to  be  a  recipe  for  software  design,  but  rather  a  discussion 
of  some  important  principles  and  practices:  modularity, 
standardization,  efficiency,  stability,  flexibility, 
extensibility,  and  documentation. 
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2 .  1  Modularity 

Sharp  (1970)  distinguishes  between  software  engineering 
and  software  architecture,  emphasizing  that  'little  or  no 
regard  is  being  paid  to  architecture* .  It  is  the  architect 
who  designs  software.  He  writes  the  software  specification, 
and  decides  how  the  system  is  to  be  constructed  by  the 
programmers.  The  major  factor  determining  how  a  system  will 
be  constructed  is  the  modular  structure  of  the  system 
outlined  by  the  software  architect.  It  is  the  degree  to 
which  the  architect  should  make  the  software  modular  that  is 
cf  concern  here. 

In  the  simplest  case,  a  module  may  be  defined  as  a 
closed  subroutine.  Sperry  Band  (UNIVAC  1959)  defines  a 
closed  subroutine  as:  *a  subroutine  not  stored  in  the  main 
path  of  the  routine.  Such  a  subroutine  is  entered  by  a  jump 
operation  and  provision  is  made  to  return  control  to  the 
main  routine  at  the  end  of  the  operation.  The  instructions 
related  to  the  entry  and  re-entry  constitute  a  linkage. ' 

The  idea  of  modularity  at  many  levels  is  expressed  in 
the  IBM  (1970-4)  definition  of  a  program  module:  'The  input 
to,  or  output  from,  a  single  execution  of  an  assembler, 
compiler,  or  linkage  editor;  hence,  a  program  unit  that  is 
discrete  and  identifiable  with  respect  to  compiling, 
combining  with  other  units,  and  loading.' 

Software  should  be  modular  at  a  number  of  levels. 
Modularity  allows  the  programmer  to  be  concerned  with  one 
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part  of  the  software  at  a  time.  This  makes  software 
development  easier  and  facilitates  changes  to  the  system  by 
modular  replacement.  A  module  may  be  viewed  as  a  single, 
very  powerful  operation.  The  highest  level  module  is  the 
complete  system  itself.  The  designer  can  therefore  create  a 
structure  of  modules,  with  many  small  logical  units 
combining  to  form  the  total  system.  Figure  2-1  is  an 
example  of  this  type  of  structure  within  GRIDSUB.  An 
explanation  of  the  modules  mentioned  in  this  figure  will  be 
found  in  Appendix  I. 

In  addition  to  the  modules  shown  in  Figure  2-1,  there 
are  modules  which  are  referenced  by  other  modules  at  the 
same  or  higher  levels.  One  such  module,  XANDY,  used  to 
calculate  co-ordinates  for  GRID  code,  is  referenced  by  most 
of  the  Block  Definition  Routines. 

Modularity  must  be  approached  carefully  and  with 
considerable  forethought.  For  each  module,  the  designer 
needs  to  describe  carefully: 

(1)  Interface:  The  interface  consists  of 
linkage  between  modules  and  communication 
between  modules.  Linkage  involves  passing 
and  returning  control,  whereas  communication 
involves  the  passing  of  parameters.  The 
interface  allows  the  user  to  treat  the  module 
or  group  of  modules  being  called  as  a  single, 
very  powerful  instruction. 

(2)  Functional  Specification:  The  functional 


' 
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specification  is  a  detailed  description  of 
the  information  (parameters)  required  by  the 
module;  the  operations  the  module  is  to 
perform;  the  parameters  set  or  returned  by 
the  module,  and  the  modules,  if  any, 
referenced  by  the  module  being  described. 

An  example  of  modularity  increasing  system  efficiency 
in  a  restrictive  environment  is  given  below.  Consider  the 
case  where  the  software  performs  many  repetitive  operations. 
Straight-line  coding  might  not  be  acceptable  because  of 
limitations  of  core  size.  However,  the  operation  could  be 
programmed  as  a  module,  thus  reducing  the  overall  size  of 
the  software.  The  software  would  then  consist  of  a 
relatively  small  mainline  program  that  calls  the  many 
modules;  probably  some  of  these  modules  would  be  used  only 
rarely,  while  others  would  be  called  a  great  deal.  The 
modular  form  of  a  program  can  reduce  the  system  overhead  in 
a  paging  environment  by  reducing  page  faulting.  Page 
faulting  occurs  when  a  reference  is  made  to  a  page  which  is 
net  in  core.  When  a  page  fault  cccurs,  the  operating  system 
removes  a  page  and  brings  in  the  reguired  page.  Obviously, 
excessive  page  faulting  can  greatly  increase  software 
overhead.  By  organizing  the  modules  in  such  a  manner  that 
the  mainline  and  the  most  used  modules  are  loaded  together, 
they  will  tend  to  be  loaded  on  the  same  page  or  group  of 
pages.  Most  paging  algorithms  will  not  remove  from  core 
pages  that  have  a  high  number  of  references  to  them  unless 
absolutely  necessary.  Hence,  page  faulting  is  likely  to 
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occur  only  on  the  pages  containing  the  least  frequently  used 
modules,  and  thus  the  paging  overhead  should  be  minimal. 

Modularity  is  also  of  value  in  non-paging  environments, 
especially  when  overlaying  is  used.  Overlaying  is  a 
technique  for  bringing  routines  into  core  from  external 
storage  as  they  are  needed,  so  that  several  routines  will 
occupy  the  storage  but  at  different  times.  This  is  used 
when  memory  requirements  exceed  available  memory.  It  is 
generally  up  tc  the  programmer  to  determine  the  overlay 
structure.  The  overhead  involved  with  overlaying  can  be 
kept  to  a  minimum  by  carefully  setting  up  the  overlay 
structure  so  that,  if  possible,  modules  used  a  great  deal 
are  not  overlaid,  or  if  they  are  overlaid,  it  is  only  with 
routines  that  are  used  infrequently.  In  this  manner  the 
number  of  overlay  operations  required  should  be  greatly 
reduced . 


Another 

advantage  of  a  mo 

dular 

system  is 

the 

ability 

to 

construct 

a 

program  library. 

The 

modules  of 

the 

system 

are 

combined 

to 

form  a  single 

data 

set  which 

includes 

a 

directory  for  identifying  and  locating  the  modules  in  the 
library.  The  loader  or  linkage  editor  program  supply  the 
modules  needed  by  the  user’s  program  from  the  library.  The 
loader  includes  only  the  modules  referenced.  This  can 
result  in  a  considerable  saving  in  space  for  the  user  who  is 
using  only  a  subset  of  the  entire  system  contained  in  the 
library. 
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Modularity  must  also  be  approached  with  caution.  It  is 
very  easy  to  make  a  system  too  modular.  If  every  module  is 
a  closed  subroutine  then  a  register  save  and  restore  will  be 
performed  every  time  the  subroutine  is  used.  If  the  module 
is  rarely  used,  it  may  not  be  practicable  to  implement  the 
routine  as  a  separate  subroutine  with  its  own  entry  and 
exit,  but  it  would  be  preferable  tc  add  the  necessary  code 
to  the  routines  requiring  this  function. 

Another  important  consideration  is  the  compilation  or 
assembly  charge  for  small  modules.  Since  most  assemblers 
and  compilers  have  a  substantial  initialization  cost 
compared  to  the  cost  of  compiling  a  small  subroutine,  it  may 
be  considerably  cheaper  to  combine  several  subroutines  in 
one  assembly  or  compilation. 

In  summary,  programming  a  large  software  system  as  a 
set  of  clearly  defined  modules  is  essential  because  the 
project  can  be  broken  down  into  more  manageable  pieces, 
thereby  allowing  group  development  on  small  pieces  of 
software  that  are  clearly  defined.  Changes  in  functional 
requirements  or  hardware  specifications,  either  during 
development  or  later,  may  involve  changes  only  to  isolated 
modules.  Finally,  modular  design  of  software  may  increase 
efficiency  and  simplify  the  software  in  a  restrictive 
environment,  where  the  total  system  is  too  large  for  the 
environment  at  any  one  time  and  the  use  of  overlay 
structures  cr  paging  is  required. 
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Tree-Like  Structure  of  GPItSUB  fodules 


1 1 


2.2  Standardization 


Maintenance  is  a  very  important  and  large  job  which 
normally  falls  on  systems  programmers  who  have  had  no 
previous  contact  with  the  software.  This  unfamiliarity  with 
software  arises  when  one  installation  or  manufacturer  writes 
software  that  is  distributed  to  many  installations.  In 
order  to  make  this  job  as  straightforward  as  possible, 
standardization  of  programming  practices  is  important.  For 
many  of  the  areas  that  require  standardization,  certain 
conventions  will  be  laid  down  in  the  software  specification. 
This  section  will  describe  some  cf  the  things  that  should  be 
standard  practice  for  all  software  designers. 


(1)  Linkage  Conventions 

Linkages  are  normally  standardized  for 
an  operating  system.  By  following  the 
standardized  linkage  convention  for  system, 
it  is  relatively  simple  to  rewrite  or  add  a 
subroutine  to  a  software  system,  with  few 
changes  to  other  routines.  A  standardized 
linkage  convention  facilitates  updating  and 
changing  modules  within  a  large  system,  with 
a  minimum  of  interference  among  other 
subroutines.  This  also  allows  modules 
developed  for  one  system  to  be  used  in 
another  system. 
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(2)  Programming  Practices 


Whenever  pos 

sible 

symbolic  address 

ing 

should  be 

used , 

even 

for  absolute 

ex- 

pressions . 

This 

can  be  very  helpful 

f  or 

debugging 

and  when 

making 

alterations  if 

the 

assembler 

or  compiler 

provides  a  cro 

ss- 

reference  table  fcr  all  symbols. 


A  good  rule  for 
follow  is:  DO  NOT 
systems  are  generally 
than  one  installation 
maintained  by  many 
who  writes  code  that 
understand 
maintenance 
also  made  by 


software  designers  to 
BE  SNEAKY.  Software 
written  for  use  at  more 
and  will  probably  be 
people.  The  programmer 
very  difficult  to 
job  of  program 
point  is 


is 

makes  the 

very  difficult.  This 
Brooks  and  Iverson  (1969) 


With  standardization,  as  with  virtually 
everything  in  computer  software,  it  is 
difficult  to  define  at  what  points  trade-offs 
should  be  made.  For  example,  how  much  time 
or  space  must  be  saved  to  justify  writing 
code  that  modifies  itself  at  execution  time? 
In  particular,  if  it  is  nearly  impossible  to 
understand  what  the  programmer  was  trying  to 
do,  then  the  benefits  derived  are 
overshadowed  by  its  lack  of  flexibility. 
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This  is  an  important  question  for  programmers 
who  write  low-level  system  software.  Modules 
at  this  level  are  used  repeatedly  by  the 
system,  so  efficiency  is  very  important. 
However,  it  is  vital  that  the  system 
programmers  maintaining  the  system  can 
understand  what  the  module  does  and  how  it 
works. 

(3)  Operating  System  Independence 

An  operating  system-independent  module 
is  a  module  that  does  not  require  any  of  the 
services  provided  by  the  operating  system. 
For  example,  the  module  contains  no 
input/output  requests  or  requests  for 
storage. 

Whenever  possible,  programmers  attempt 
to  make  as  many  modules  as  possible 
independent  of  the  operating  system.  Hence, 
if  the  software  is  to  be  used  on  another 
operating  system,  many  modules  will  not 
require  changes.  For  example,  a  language 
processor  such  as  a  FORTRAN  compiler  should 
be  designed  with  as  many  modules  as  possible 
completely  operating  system-independent. 
Only  modules  such  as  input/output  modules 
will  then  require  changes  before  the  compiler 


can  be  used  under  another  operating  system 


With  a  well-defined  interface  and 
functional  specification  for  a  module  which 
is  to  be  changed,  it  is  a  relatively  simple 
matter  to  change  the  compiler  so  that  it 
functions  under  a  different  operating  system. 

(4)  Program  Documentation 

Documentation  will  be  discussed  more 
completely  in  a  later  section.  Regardless  of 
the  method  of  documentation  chosen,  it  should 
be  consistent  throughout  the  software. 
Consistency  of  structure  and  style  will  allow 
the  programmers  who  are  working  with  the 
system  to  find  information  quickly,  since 
documentation  structure  is  the  same  for  all 
parts  of  the  software. 

2.3  Efficiency  and  Stability 

The  cost  of  using  software  is  a  very  important 
consideration  in  any  software  development  project.  The 
designer  and  programmer  should  attempt  to  design  and  write 
software  that  is  as  compact  and  as  fast  as  possible. 
Software  also  must  be  stable.  Stable  software  is  software 
that  has  most  'bugs'  removed  and  is  not  likely  to  'crash'  or 
'hang-up'  if  it  receives  erroneous  input.  Rather  than 
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'crashing '  ,  e 
error  handled 
new  input, 
which  increase 
unstable  soft 
costly  softwar 
respond  with  a 
diagnostic,  a 
worst  of  all. 


xplanatory  messages  shou 
in  an  appropriate  manner. 
Thus  stability  involves 
s  the  cost  of  using  the 
ware  discourages  users  ev 
e.  If  the  user  makes  an  e 
n  explanatory  diagnostic, 
n  uninformative  message,  a 
erroneous  results. 


Id  be  given  and  the 
such  as  asking  for 
checking  for  errors, 
software.  However, 
en  more  quickly  than 
rror,  the  system  may 
an  error  recovery 
software  crash,  or. 


Frequently,  large  and/or  complex  software  systems  are 
programmed  with  two  or  more  levels,  as  explained  in  the 
section  on  modularity.  The  highest  level  consists  of  the 
modules  that  are  called  by  the  user.  The  highest  level 
modules  give  error  diagnostics  and  possibly  attempt  error 
recovery.  Ths  needed  stability  is  provided  at  this  level. 
These  routines,  often  without  the  user  being  aware  of  it, 
call  subroutines  at  a  lower  level.  For  example,  when  a 
programmer  codes  a  READ  or  WRITE  statement,  it  appears  to 
him  that  the  FORTRAN  compiler  will  generate  the  code 
necessary  to  perform  the  input  or  output.  Actually,  the 
compiler  gererates  code  to  call  the  low-level  input/output 
routines  provided  by  the  operating  system.  These  lower 
level  routines  may  have  been  written  on  the  assumption  that 
calls  to  them  will  be  correct,  that  is,  any  erroneous  data 
will  have  been  detected  before  a  call  is  made.  If  an  error 
happens  to  be  detected  at  this  level,  the  messages  are 
generally  very  uninformative,  for  example,  'SYSTEM  ERROR' 


. 
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and  an  error  found  at  this  level  will  probably  cause  the 
program  to  be  abnormally  terminated. 

One  advantage  of  having  routines  at  more  than  one  level 
is  efficiency.  The  higher  level  routines  are  called  by  most 
users.  However,  the  programmer  who  wants  a  particularly 
efficient  operation  will  use  the  lower  levels,  even  though 


his  programming  may  be 

more 

involved. 

This 

allows 

programmers  the  opportunity 

to 

design 

eff 

icient 

systems 

built  on  another  system. 

An 

example 

of 

this 

type  of 

hierarchical  structure  in  IBM'S  Operating  System/360  (1970- 
5)  is  the  Queued  Sequential  Access  Method  (QSAM) ,  which  is  a 
level  above  the  Execute  Channel  Program  routines  (EXCF) , 
that  is,  the  QSAM  routines  make  use  of  the  EXCP  routines. 

The  more  services  that  are  provided  by  the  software, 
the  greater  the  cost  will  be  to  the  user  of  the  software. 
Tasks  such  as  providing  error  checking  diagnostics  and 
debugging  aids  involve  considerable  overhead.  Eecause  of 
this  overhead,  most  large  software  systems  should  provide 
the  user  with  a  multi-level  structure,  such  as  the  structure 
mentioned  above,  where  the  user  can,  if  he  wants,  obtain 
efficiency  at  the  cost  of  stability  with  slightly  more 
programming  effort. 
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2.4  Flexibility  and  Extensibility 

Software  packages  should  allow  the  user  to  perforin  some 
set  of  actions  efficiently  and  with  a  minimum  of  effort.  In 
particular,  software  packages  should  be  user-oriented.  A 
software  system  that  makes  it  difficult  for  the  user  to  do 
what  he  wants  will  not  be  used. 

A  great  deal  of  effort  is  spent  on  the  implementation 
of  software  packages.  This  effort  can  to  some  degree  be 
wasted,  if  insufficient  thought  is  given  to  the  design  of 
the  software  before  implementation  begins.  Software  that 
binds  the  user  to  a  very  limited  set  of  operations  that  can 
not  be  extended  will  last  only  a  short  time,  and  then  be 
replaced  by  something  that  may  be  only  slightly  better. 
This  quick  replacement  of  software  packages,  because  of  a 
lack  of  flexibility  and  extensibility,  is  very  expensive  and 
wasteful.  Overall,  it  would  be  cheaper  to  consider  more 
thoroughly  the  needs  of  the  user,  and  design  software  that 
is  flexible  and  extensible. 

Software  packages  that  are  too  general-purpose  tend  to 
become  inefficient.  As  more  options,  alternatives,  and 
features  are  added  to  a  system,  more  checking  and  decision 
making  is  required  to  decide  what  is  to  be  done.  A  well- 
designed  software  package  should  be  no  more  general  than 
necessary,  but  be  flexible  and  extensible  enough  for  changes 
and  additions  to  be  made  to  meet  most  future  needs. 
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This  idea  has  been  expressed  by  Lampson  (1970).  'If  a 
system  is  to  evolve  to  meet  changing  requirements,  and  if  it 
is  to  be  flexible  enough  to  permit  modularization  without 
serious  loss  of  efficiency,  it  must  have  a  basic  structure 
that  allows  extensions  not  only  from  a  basic  system  but  also 
from  some  complex  configuration  that  has  been  reached  by 
several  prior  stages  of  evolution.  In  other  words,  the 
extension  process  must  not  exhaust  the  facilities  required 
for  further  extensions.  The  system  must  be  completely  openr 
endedj,  so  that  additional  machinery  can  be  attached  at  any 
point.*  One  may  not  always  foresee  all  possible  uses  for  a 


software 

package.  It 

is  possible  to 

implement 

data 

structures 

that  are 

efficient  and  open 

to  extension. 

An 

example  of 

this  type  of 

structure  is  given 

in  Section 

3.4. 

This  type 

of  design 

will  allow  software 

packages  to 

last 

rather  tha 

n  have  only  a 

short  life. 

2.5  Documentation 

Three  basic  pieces  of  documentation  are  needed  to 
describe  a  software  project.  The  first  is  the  software 
specification  written  before  the  software  is  coded,  and 
which  is  used  as  a  guideline  for  implementation  of  the 
software.  The  remaining  two  documents,  the  Internal  Logic 
Manual  and  the  User's  Guide,  describe  the  software  after 


development 
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2.5.1  Software  Specification 


There  are  many  different  methods  proposed  in  the 
literature  for  writing  software  specifications  :  *How  To 
Write  Software  Specifications*  (Hartman  And  Owens  1967) ,  *A 
Guide  For  Software  Documentation*  (Walsh  1969),  and 
•Documentation  Standards*  (Gray  And  London  1970)  Are 
Examples.  The  methods  vary  greatly.  However,  most  are 
oriented  towards  the  design  cf  large-scale  software  by 
manufacturers.  It  is  not  possible  to  state  that  one  method 
is  better  than  another,  for  needs  vary  greatly  between 
installations.  The  intention  here  is  to  emphasize  the 
importance  and  value  of  an  adequate  software  specification. 
There  is  a  tendency  to  begin  programming  without  the  initial 
step  of  writing  a  software  specification  because  of  the 
amount  of  work  involved.  Neglecting  this  step  is  generally 
more  costly  in  the  long  run,  for  problems  which  were  not 
foreseen  may  require  the  recoding  of  large  sections  of  the 
software.  If  the  implementor  has  a  clear,  precise,  well- 
explained  document  before  him  from  which  he  may  code  the 
software,  the  implementation  will  proceed  much  more  rapidly 
and  with  less  likelihood  of  running  into  unexpected 
problems . 


One  possible  way  to  design  and  organize  a  software 
specification  is  given  below.  Fixed,  rigid  rules  for 
writing  a  specification  are  not  given.  Instead,  a  few  basic 
principles  are  given  that  can  be  applied  by  the  designer  in 
a  way  that  best  suits  the  situation. 


If  • 


20 


Initially,  after  having  given  some  thought  to  the 
problem,  the  designer  should  attempt  to  formulate  a  method 
for  the  storage  and  organization  of  the  information  that 
will  be  used  and  manipulated  by  the  software  system.  This 
method  of  organization  of  the  data  is  commonly  called  a  data 
structure.  If  the  problem  or  system  being  programmed  is 
fairly  large,  it  can  probably  be  broken  down  into  several 
distinct  parts,  each  of  which  will  have  its  own  data 
structure (s) .  Obviously,  if  the  problem  is  large,  it  is 
likely  that  the  first  attempt  at  organizing  the  data 
structure  will  not  be  adequate. 

By  breaking  the  system  down  into  logically  separate 
components,  the  designer  may  begin  to  develop  a  modular 


system . 

By  taking  one 

logical 

unit 

at 

a  time 

and 

considering 

the  interaction 

of 

this 

unit 

with  the 

data 

structure , 

inadequacies 

in 

the 

data 

structure 

may  begin  to 

appear.  These  may  result 

in 

the 

formulation 

of 

a  new 

data 

structure . 

This  time. 

th 

e  designer 

has  more 

insight 

into 

his  problem  and  may  design  a  better  data  structure.  It  is 
important  to  keep  a  record  of  changes,  so  that  at  any  time 
one  may  get  an  accurate  picture  of  the  data  structure  and 
the  functional  relationships  of  the  modules  that  so  far  have 
been  proposed.  The  description  of  the  functional 
relationship  of  the  module  to  the  data  base  is  commonly 
referred  to  as  the  functional  specification. 


The  way  in  which  a  written  record  is  kept  of  the  data 
structure  (s)  and  functional  specifications  will  vary  greatly 
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free  person  to  person  and  possibly  problem  to  problem.  Some 
people  may  prefer  diagrams  and  flowcharts,  while  ethers 
prefer  written  notes.  Many  different  systems  and  foras  have 
been  suggested  and  produced  for  this  type  of  documentation , 
and  the  designer  must  decide  which  aethod  is  test  suited  to 
his  needs. 


As  this  process  of  modifying  and  redefining  the  data 
structure  (s)  and  defining  of  functional  specification  for 
modules  goes  on,  the  designer  may  begin  to  see  that  the 
logical  units  proposed  for  the  system  are  not  a  complete 
set,  or  not  as  clearly  defined  as  was  first  thought.  This 
may  require  the  redefining  of  some  modules,  tut  eventually 
the  system  will  take  shape  on  paper.  If  a  thorough  iob  has 
teen  done,  the  greatest  part  of  the  design  work  is  complete. 


The  third  part  of  the  total  specification  is  the 
interface  specification  for  each  module,  that  is,  a 
specification  of  how  modules  will  link  together  and  exchange 
information.  To  a  large  degree,  the  way  the  interface  is 
accomplished  will  be  defined  for  the  operating  system 
(Appendix  III) .  However,  what  information  is  to  te  passed 
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In  summary,  three  parts  are  reguired  for  a  software 
specification : 

1.  Definition  of  data  structure  (s) . 

2.  Functional  specifications  for  each  module. 

3.  Interface  specification  between  modules. 

The  importance  of  an  adequate  and  complete 
specification  for  the  implementation  of  software  cannot  be 
over-emphasized.  If  the  programmer  is  presented  with  a 
complete  and  detailed  definition  of  the  system, 
impl  ementaticn  can  be  realized  quickly  with  little 
likelihood  of  unexpected  problems. 
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2.5.2  Internal  Logic  Documentation 

Once  the  software  is  completed  it  is  essential  that  its 
internal  logic  he  documented.  Maintenance  can  be  a  tiring 
and  unrewarding  job,  and  the  job  made  even  more  tedious, 
perhaps  even  impossible,  if  the  software  is  not  adeguately 
documented . 

Again,  as  with  the  software  specification,  many  methods 
have  been  suggested  for  the  construction  of  internal  logic 
documentation.  Walsh  (1969)  and  Gray  and  London  (1970) 
provide  examples  of  various  methods  for  internal  logic 
documentation.  In  general,  the  methods  suggested  for 
documentation  tend  to  be  very  involved  and  reguire 
substantial  resources  to  produce  and  maintain.  This  is 
generally  not  acceptable  if  the  software  being  produced  is 
the  work  of  a  small  group  with  very  limited  resources. 

Walsh  (1969)  offers  a  format  in  her  book  'A  Guide  For 
Software  Documentation*  that  appears  to  be  very  complete  and 
easy  to  adapt  to  special  needs.  Figure  2-2  is  an  example 
taken  from  her  book. 

Regardless  of  the  form  chosen,  there  are  several 
important  pieces  that  together  form  complete  internal  logic 
documentation.  First,  there  are  the  actual  listings  of  the 
system  which  should  be  well  'commented*,  and  organized  in  a 
manner  that  allows  any  module  to  be  found  rapidly.  Second, 
there  is  the  written  documentation  which  gives  an  overview 
of  the  total  system  as  a  collection  of  interacting 
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boxes'  as  well  as  a  detailed  description  of  each  'black-box' 
or  module.  The  written  documentation  should  also  include  a 
detailed  explanation  of  the  tables  and  data  structures  used 
in  the  system.  Third,  there  should  be  flowcharts  describing 
the  whole  system  in  general  and  each  module  in  detail. 
Finally,  there  should  be  a  maintenance  sheet  so  that  changes 
to  the  system  can  be  recorded.  Section  3.5.2  and  Appendix 
IV  give  examples  of  this  type  of  documentation  for  GRIDSUE. 

An  example  of  complete  internal  program  logic 
documentation  can  be  seen  in  the  way  IBM  has  documented  the 
software  for  Operating  System  /360  with  publications  called 
Program  Logic  Manuals  or  FLMs  (IEM  1970-3) .  A  view  of  the 
completeness  cf  this  documentation  can  be  seen  in  Figure  2- 
3.  listings  for  the  system  modules  are  available  on  micro¬ 
fiche  and  included  as  part  of  the  entire  system 


documentation . 
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2.5.3  User  1 s  Guide 

As  with  the  ether  forms  of  documentation,  there  are 
many  methods  for  documenting  a  system  so  that  the  user  may 
understand  the  system  and  use  it  effectively.  The  User’s 
Guide  is  quite  distinct  from  the  internal  logic 
documentation,  whose  main  function  is  to  describe  how  the 
system  works.  The  typical  user  does  not  require  this 


knowledge,  and  the  User’s 

Guide  is 

intended 

for 

people 

wishing  to  learn  only  how 

to  use  the 

system . 

The  internal 

logic  documentation  is 

inte  nded 

primarily 

for 

the 

maintenance  personnel. 

Generally,  user’s  guides  are  written  by  someone  who  has 
developed  or  helped  to  implement  the  software. 

It  is  difficult  to  say  what  user’s  guides  should  and 
should  not  contain.  The  level  of  expertise  of  users  may 
vary  greatly,  from  novice  programmers  to  experienced  systems 
programmers.  It  is  important  that  this  documentation  be 
complete  enough  so  that,  with  the  User’s  Guide  alone,  the 
system  may  be  used  by  the  novice.  It  is  the  content,  not 
the  style,  that  is  most  important. 

Again,  some  of  the  best  and  most  complete  examples  of 
user  documentation  are  the  publications  produced  by  IBM  for 
Operating  System  /360  (IBM  1970-3) .  These  publications  are 
grouped  under  the  general  heading  of  System  Reference 
library  Publications  (SRIs)  and  are  distinct  from  the  PIMs. 
Figure  2-4  gives  an  overview  of  the  SRLs  for  Operating 
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System/360.  The  SRLs  are  intended  to  be  general  information 
for  users,  whereas  the  PLMs  are  intended  for  maintenance 
personnel. 


An  important  requirement  for  all  three  forms  of 
documentation  is  that  updating  be  systematic.  As  the  system 
evolves  and  is  developed  or  expanded,  it  is  important  to 
document  the  changes,  so  that  the  documentation  describes 
the  system  as  it  exists  at  the  present  time.  If 
documentation  is  well-organized  in  distinct,  well-defined 
sections,  changes  to  the  system  may  require  changes  only  to 
isolated  sections  of  the  documentation.  One  possible 
solution  is  the  use  of  text  processing  packages  to  maintain 
and  update  the  documentation.  Packages  such  as  TEXT/360 
(IBM  1969-6)  and  FMS  (Silver  1969)  are  very  convenient  for 
maintaining  documentation. 


As  changes  occur 
replace  the  changed 
Periodically,  a 
which  will  incorporate 
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produced. 
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in  the  documentation, 
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may  be  made  and  new  copies  or 
disadvantage  of  such  a  system 
many  copies.  however,  if  one 
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CHAPTER  III 


SOFTWARE  DESIGN  PRINCIPLES  ILLUSTRATED  IN 


A  GRAPHICAL  SUBROUTINE  PACKAGE 


3.0  Introduction 

GRIDSUB ,  a  Graphical  Subroutine  Package,  was  originally 
proposed  and  written  by  W.H.  Huen  (1969).  The  first  package 
was  designed  to  operate  on  a  Control  Data  Corporation  GRID 
(Graphical  Remote  Interactive  Display)  Graphic  Terminal 
Subsystem  (CEC  1969)  with  one  bank  (4096-12  bit  words)  of 
core.  Extension  of  the  GRID  hardware  to  three  tanks  made 
the  old  software  obsolete. 

A  new  GRIDSUB  package  has  been  written  by  the  author  to 
operate  on  the  extended  GRID  hardware.  This  new  package  was 
written  to  be  compatible  with  the  old  GRIDSUB  for  most 
applications  programs,  except  that  software  capabilities  for 
handling  large  application  programs  were  increased  by  the 
hardware  extension. 


The  original  subroutine  package  was  written  in  FORTRAN. 
The  new  system  was  written  in  System/360  Assembler  Language 
(I EM  1970-2)  to  achieve  greater  efficiency  and  compactness. 
Although  the  internal  structure  of  the  new  system  is 
completely  changed,  any  program  which  worked  with  the  old 
system  should  work  on  the  new  system,  unless  nested  blocks 
(Huen  1969)  are  used.  The  nested  block  feature  is  not 
available  at  this  time  in  the  new  GRIDSUB. 


I  I 
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An  objective  in  re-writing  GFIDSUB  was  to  design  the 
software  package  in  a  manner  which  demonstrates  the  general 
principles  of  software  design  discussed  in  Chapter  II.  This 
chapter  relates  the  principles  discussed  in  Chapter  II  to 
the  actual  implementation  and  design  of  the  new  GFIDSUB. 

3.1  Modular  Construction  Cf  GFIDSUB 

The  twc  previous  definitions  of  modularity,  given  in 
Chapter  II,  both  apply  to  GFIDSUB  modules.  Each  GFIDSUB 
routine  is  a  closed  subroutine  that  is  not  stored  in  the 
main  path  of  another  routine  and  is  entered  by  a  jump 
operation.  Every  GFIDSUB  routine  is  a  program  unit  that  may 
form  the  input  to  or  output  from  a  single  execution  of  the 
assembler  and  is  discrete  and  identifiable  with  respect  to 
combining  with  other  program  units  and  loading. 

The  linkages  between  all  subroutines  of  GFIDSUB  are  the 
standard  calling  seguences  defined  for  IEM  software.  This 
allows  all  routines  to  be  called  from  FOFTFAN  routines  and 
facilitates  ease  of  communication  within  GFIDSUB. 

Examples  of  a  module*s  functional  specification  are 
included  in  the  section  dealing  with  GFIDSUB  documentation. 

The  set  of  GFIDSUB  modules,  which  are  explained  in 
Appendix  I,  may  be  classified  into  four  categories;  each 
category  containing  modules  for  a  set  of  related  functions. 

Block  Definition 


BLOCK 


ENEBLK 


PCINTX 


. 

„  •  .  :!  «  1  2  DO 


■ 
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WOVE 


VECTOR 


TEXT 


DUNE 


IDY 


■Display  Definition  and  Transmission 


DISPLY 


TRANMT 


DLPEN 


D ALPHA 


DFKEY 


DVECT 


DPOINT 


DEND 


Display  Modification 


MOVEBK 


DELB  LK 


FREEBK 


ERSEK 


DELID 


RSTBK 


The  above  four  categories  may  also  be  considered  to  be 
the  four  types  of  graphical  functions  performed  by  an 
interactive  graphics  program  using  GRIDSUB. 

In  a  typical  case,  a  user's  pregram  will  initially  call 
the  block  definition  routines  to  define  the  basic  pictoral 
entities  to  be  displayed.  The  program  will  then  call  the 
display  definition  and  transmission  routines  to  define  his 
picture  and  send  it  to  GRID  for  display.  Upon  return  from 
the  transmission  routine,  the  user  has  available  tc  him  the 
message  created  at  the  graphics  terminal  by  the  operator. 
The  program  will  interpret  this  message  with  the  aid  of  the 
decoding  routines.  Based  on  the  interpretation  of  the 
decoded  message,  the  program  will  modify  the  picture  using 
the  display  modification  routines.  Definition  of  new 
elements  to  be  added  to  the  picture  will  result  in  the 
program  again  calling  the  block  definition  routines. 


. 
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Essentially,  an  interactive 
interpreter  cf  messages  comprised 
picks,  pressing  of  function  keys) 
operator. 


graphics  program  is  an 
of  actions  (light  pen 
performed  by  the  console 


The  seguence  just  described  is  a  logical  ordering  that 
describes  the  structure  of  most  interactive  graphics 
programs  using  GRIDSUB. 

Using  the  four  categories  cf  routines  defined  above,  it 
should  be  possible  to  reduce  the  paging  requirements  of  most 
application  pregrams  by  loading  those  GRIDSUB  routines  in 
cne  category  on  the  same  page  or  greup  of  pages.  Thus, 
block  definitions  can  be  performed  with  a  minimum  number  of 
pages  required  in  core.  This  reduces  paging  overhead  by 
requiring  the  user  to  reference  as  few  pages  as  possible. 
The  likelihood  of  all  these  pages  remaining  in  core  for  the 
duration  of  the  block  definitions  is  much  higher  than  if  the 
block  definition  routines  were  spread  throughout  most  pages 
of  the  GRIDSUB  system. 

As  an  application-oriented  package  becomes  larger  and 
more  diversified  the  application  package  is  often  made 
available  to  the  user  as  a  library  in  a  single  data  set  that 
contains  modules  and  a  directory  which  identifies  and 
locates  the  modules.  The  advantage  of  a  library  is  that  the 
user's  program  has  loaded  with  it  only  those  routines  tc 
which  it  refers  either  directly  cr  indirectly. 

In  any  environment  where  the  user  is  charged  for  the 


. 
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memory  space  that  his  program 
provide  a  saving  if  the  user  is 
stored  in  the  library. 


requires , 
not  using 


a 

all 


library  can 
the  routines 


Under  the  M. 
multiplying  the 
virtual  memory  in 
can  vary  at  exe 
charge.  This  is 
Integral.  With 
increases  as  the 
reason,  it  beco 
requirements  wher 
available  to  the 
than  as  a  single 


T.S.  system. 

the  charge 

is  com 

amount  of 

CEU  time  used 

by  the 

use.  Since 

the  amount  cf 

memory 

cution  time. 

a  running  sum 

is  kept 

referred  to 

as  the  M. T. S. 

Virt ua 

this  method,  the  charge  for  virtu 
use  of  CPU  time  increases, 
mes  important  to  reduce  the  virtu 
e  possible.  Therefore,  GRIESUB 
application  programmer  as  a  librar 
load  module. 


puted  by 
amount  of 
in  use 
for  this 
1  Memory 
al  memory 
For  this 
al  memory 
was  made 
y,  rather 


A  charge  for  memory 
systems.  For  this  reason, 
economical  method  for  makin 
the  cost  of  searching  the  dir 
should  be  weighed  carefully 
which  is  the  best  method. 


requirements  is  typical  of  most 


a  library  may  be 

the 

most 

g  a  system  available. 

How 

ever , 

ectory  and  the  saving 

in 

space 

befere  a  decision  is 

made 

as  to 

Graphical 
relatively  h 
proportion  of 
at  the  graph 
picture-modif y 
on  what  he 
the  low  proper 


application  programs  tend  to  have  a 
igh  ’in-core*  time  with  a  relatively  low 
CPU  time  used,  due  to  the  operator  interaction 
ics  terminal.  The  operator  requests  some 
ing  action  and  then  studies  the  result.  Based 
sees,  a  new  command  is  given.  This  results  in 
tion  of  CPU  time  utilized  by  the  program. 
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usually  1%  to  10%.  For  this  reason,  if  a  memory  charge  is 
assessed  on  the  basis  of  elapsed  time,  reduction  of  memory 
requirements  becomes  extremely  important  if  interactive 
graphics  is  tc  be  economical.  In  a  multiprogramming  system, 
the  use  of  a  program  library  may  be  the  most  effective  way 
to  reduce  virtual  memory  charges  for  the  typical  user,  who 
is  using  only  a  subset  of  the  total  system. 

* 

3.2  Standardization  in  GRIDSUB 

The  designers  of  a  system  usually  do  not  maintain  the 
system  once  it  has  been  completed  and  is  in  use.  The  task 
of  maintenance  often  falls  to  people  who  have  not  had  any 
previous  contact  with  the  software.  To  aid  maintenance 
personnel,  designers  should  attempt  to  write  the  software  in 
a  consistent  manner,  observing  as  many  standard  practices  as 
possible. 

During  the  design  of  GRIDSUE,  attempts  were  made  to 
follow  the  following  standard  software  practices: 

(1)  Linkage  Conventions 

The  GRIDSUE  system  was  designed  to  be 
available  under  two  operating  systems,  OS/360 
and  M.T.S.  Both  operating  systems  use  the 
standard  CS  type  calling  sequence  (IBM  1970- 
5)  shown  in  Appendix  III. 


The  standard  linkage 


conventions 


make 


r<  n  o  o  b 
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inter-program  communication  and  module 
replacement  very  straight-forward.  A 

valuable  debugging  aid  is  provided  by  a 
record  of  register  contents  and  a  trace  of 
the  routines  through  which  control  has  passed 
shown  by  means  of  the  forward  and  backward 
pointers  in  the  save  areas  (Figure  3.1). 

(2)  Programming  Practices 

Throughout  GRIDSUB,  register  numbers 
have  been  equated  (IBM  1970-2)  to  symbolic 
names.  GRIDSUB  is  assembled  using  the  M.T.S. 
(G)  Assembler  (University  cf  Alberta  1970) 
which  provides  a  complete  cross-reference 
table  for  all  symbols  used  in  an  assembly. 
This  is  just  one  example  of  what  was  defined 
earlier  (Chapter  II)  as  a  good  programming 
practice. 

Within  GRIDSUB,  symbolic  names  have  been 
used  as  labels  for  branch  instructions  rather 
than  branching  by  using  displacements.  For 
example : 

B  START  ERANCH  TO  START 

is  used  rather  than: 

B  *+30  BRANCH  30  BYTES  FORWARD 

This  method,  using  symbolic  names  for 


. 
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labels,  allows  the 

programmer 

to  find  quickly 

all  references  to 

a  label 

in 

the  cross- 

reference  table  created  by 

the 

assembler. 

Use  of  symbolic 

names 

also 

allows  a 

programmer  to  insert  code  between  a  branch 
instruction  and  the  code  being  branched  to 
without  having  to  change  the  branch 
instruction . 

The  code  in  GRIDSUB  has  been  written  in 
a  straight-forward  manner.  Instructions  are 
individually  commented.  Nowhere  in  GRIDSUB 
is  code  modified  at  execution  time.  This 
approach  does  add  slightly  to  the  cost  of 
using  GRIDSUB.  However,  it  is  much  easier 
for  anyone  working  with  GRIDSUB  to  debug, 
modify,  and/or  add  code  to  GRIDSUB  routines. 

(3)  Operating  System  Independence 

Wherever  possible  GRIDSUE  was  divided 
into  modules  which  performed  one  or  more 
logical  functions.  Since  the  intention  was 
to  have  the  package  available  under  more  than 
one  operating  system,  most  of  the  modules  are 
operating  system-independent.  GRIDSUB  must 
function  under  both  M.T.S.  and  CS/360.  The 
major  change  needed  to  convert  GRIDSUB  from 
one  operating  system  to  the  other  was  in  the 
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input/output ,  both  for  error  diagnostics  to 
the  user  and  for  GRID  to  System/360 
communication.  For  this  reason,  GFIDSUB  was 
set  up  to  be  assembled  either  for  M.T.S.  or 
OS/360  from  one  source  deck  which  contained 
conditional  assemblies  (IEM  1970-2) .  For 
example,  the  following  statements  in  the 
source  program  allow  the  programmer  to  vary 
the  way  in  which  GRIDSUB  is  to  be  assembled 
by  varying  the  file  SYSTEM: 


LCIC 


COPY 


SSY  STEM 


SYSTEM 


This  file  contains  a  declaration  of  the 
conditional  assembly  variable,  SSYSTEM, 
stating  for  which  operating  system  GRIDSUB  is 
to  be  assembled.  The  COPY  assembler  command 
(IBM  1970-2)  copies  the  file  SYSTEM  into  the 
source  program  that  is  to  be  assembled.  For 
M.T.S. ,  the  file  SYSTEM  should  contain: 


SSYSTEM 


SETC 


'  MTS 


For  OS/360  the  partitioned  data  set  member 


SYSTEM  should  contain: 


SSYSTEM 


SETC 


OS 


By  changing  the  file  SYSTEM,  a  module 
which  was  not  operating  system-independent 
could  be  assembled  for  either  CS/360  or 
M.T.S.,  and  only  one  source  deck  would  be 
required.  Having  only  cne  source  deck  for  a 
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given 

module  makes  updating  of 

GRIDSUB 

routines  much  easier,  since 

there  is 

only  one 

change 

to  make  rather  than  a 

change 

to  two 

decks . 

This  virtually 

assures 

exact 

compatability  between  operating  systems, 

since  the  only  part  of  the  system  that  is 
different  is  the  part  which  is  operating 

system-dependent.  This  was  accomplished 
using  conditional  assembly  statements  such  as 
those  shown  below: 

AIE  ( *  SSYSTEM  NE  ‘OS')  -MTS 

PUT  MESSAGE, ERROR 

.MTS  AIF  (•SSYSTEM*  NE  *MTS').END 

WHITE  6, ERROR, 121 
.END  ANCP 

With  the  above  conditional  assembly 

statements,  the  PUT  macro  would  be  assembled 
if  SSYSTEM  was  set  to  *OS*.  However,  if 
SYSTEM  was  set  to  *MTS*,  then  the  WRITE  macro 
would  be  assembled. 

The  use  of  conditional  assembly 
statements  was  restricted  to  modules  which 
were  not  completely  operating  system- 
independent,  and  where  any  attempt  to  make 
them  operating  system-independent  would 
destroy  their  logical  completeness. 
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(4)  Program  Documentation 


A 

method 

of  program 

documentation 

for 

GRIDSUB 

was 

described 

in  this 

thesis . 

The 

method 

is  illustrated  in 

Section 

3.  5  of 

the 

thesis  which  will  deal  with  documentation. 

3.3  Efficiency  vs  Stability,  GRID  -  System/360  Communication 

In  attempting  to  make  GRIDSUB  a  system  of  logical  units 
cr  modules,  a  group  of  routines  was  designed  to  deal  only 
with  GRID  -  SYSTEM/360  communication.  One  routine,  WRTGRID , 
writes  to  GRID  from  System/360,  and  another  routine, 
EEAEGRID,  reads  from  GRID  at  the  System/360  end.  There  are 
complementary  routines  in  GRID  to  communicate  with 
System/360.  WRTGRID  and  REAEGPID  form  the  lower  level  of 
the  two  level  structure  for  communication  at  the  System/360 
end  . 

To  the  user  of  GRIDSUB,  it  appears  that  TRANMT  only 
prepares  messages  to  be  sent  or  received.  The  sending  and 
receiving  of  messages  is  actually  controlled  by  the  channel 
programs  issued  by  WRTGRID  and  EEAEGRID. 

Stability  is  achieved  through  the  error  checking  and 
message  preparation  in  TRANMT.  Efficiency  is  achieved  by 
having  special-purpose  I/C  routines  that  perform  no  error 
checking  on  the  information  passed  to  them  frcm  TRANMT, 
since  this  information,  assuming  TRANMT  has  no  hues,  is 
always  correct.  Any  errors  which  occur  at  this 


lower  level 
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appear  to  the  I/O  routines  as  transmission  errors. 

The  I/O  routines  do  contain  error  recovery.  This  error 
recovery  is  for  transmission  errors,  not  for  logic  errors 
due  to  erroneous  parameters  from  TRANMT.  For  this  reason, 
errors  at  this  level  produce  error  messages  indicating  unit 
checks  and  unit  exceptions  (IE  M  1969-1).  The  corresponding 
error  diagnostic  messages  tend  to  he  very  uninformative,  for 
example:  'UNIT  CHECK  IN  2701  -  SENSE  BYTE  =  01'.  Not  only 
is  this  message  uninformative  to  the  typical  user,  it  is 
also  misleading  if  the  error  was  actually  a  result  of  tad 
parameters  passed  to  the  I/C  routines.  The  case  of 
erroneous  parameters  being  passed  from  TRANMT  to  the  I/O 
routines  should  never  happen  once  the  system  is  debugged. 
However,  the  user  can  expect  this  type  of  message  if  he 
bypasses  TRANMT  for  the  sake  cf  efficiency,  and  attempts  to 
program  at  this  lower  level. 


The  major 

advantages  of 

this  type 

of  two 

1 

evel 

structure  ccme 

from  having  a 

set  of  I/O 

routines 

that 

are 

not  strictly  tie 

d  to  use  in  the 

GRIDSUB 

system , 

but 

are 

extremely  speci 

al-purpose  and 

efficient 

for  use 

in 

the 

GRIDSUB  system. 

These  routines 

are  very  si 

milar  to 

what 

is 

normally  called  device-support  routines. 

The  user  must  determine  if  the  additional  effort 
required  to  use  the  I/O  routines  directly  will  give  a 
saving  of  time  and  space  to  warrant  not  using  the 
general-purpose  routine  TRANMT,  which  provides  the  error 
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checking  and  message  preparation  that  gives  the  inter¬ 
machine  communication  stability. 


Figure  3-2  A  Lower  Level  In  Communication 
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3.4  Flexibility  and  Extensibility  in  GRIDSUB 

The  new  GRIDSUB  package  was  designed  to  appear,  to  the 
user,  identical  with  the  original  GRIDSUE.  Although  the 
internal  structure  was  changed  considerably,  the  user  who 
interfaced  with  GRIDSUB  through  the  subroutines  provided 
should  see  no  change. 

One  example  of  the  changed  internal  structure,  the  form 
of  the  Block  File,  is  given  below  to  show  hew  the  new 
GRIDSUB  uses  a  flexible  and  extensible  data  structure  to 
store  blocks  (Appendix  I) . 

The  data  structure  described  below  was  chosen  for 
several  reasons: 

(1)  The  data  structure  meets  the  needs  of  the 
GRIDSUB  system  as  it  is  currently  defined 
(Appendix  I) . 

(2)  The  data  structure  is  designed  for 
efficient,  straight-forward  garbage  col¬ 
lection  . 

(3)  The  data  structure  can  be  readily 
expanded  to  meet  an  individual  user's  needs. 

(4)  The  data  structure  uses  all  available 
space  before  garbage  collection  is  required. 

(5)  The  data  structure  should  be  able  to 
handle  most  expansions  to  the  GRIDSUE  system, 
if  an  expansion  to  the  subroutine  package  is 


desired 
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Four  pointers  or  counters  are  maintained  for  the  Block 
File  (Figure  3-3) : 

BIKFILE  -Block  File  address 

BIKSP  -Amount  of  space  available  within  the 

Block  File  (initially  the  Block  File 
size) . 

POINTER  -Address  for  next  pointer  to  code  in 

Block  File  (initially  the  end  cf  Block 
File) 

CODE  -Address  of  first  available  location  for 

code  to  be  inserted  into  the  Elcck  File 

i 

(initially  ELKFILE) . 

These  pointers  or  counters  are  updated  by  the  GRID  cede 
generaticn  rcutines  and  by  BLOCK  and  ENDBIK  (Appendix  I)  . 
The  Block  File  is  cleaned  up  by  the  garbage  collector, 
GARBAGE,  wl  ich  resets  the  pointers  cr  counters  accordingly. 

Figure  3-3  is  a  diagram  of  the  Block  File.  GRID  code 

is  added  from  the  bottom  up.  GARBAGE  is  called  when  the 

code  meets  the  pointers  (BLKSP=0) . 

A  Block  Location  Table,  BIT,  of  fixed  size,  is 

maintained  to  point  to  the  pointers  in  the  Block  File.  BIT 
is  512  four  byte  elements,  corresponding  to  the  511 

allowable  blocks.  Since  Block  0  is  not  permitted,  BLT (0)  is 
not  used  as  a  BLT  element.  The  ELT  element  address  for  a 
block  is  the  BLT  address  plus  the  BLT  displacement  (four 
times  the  block  number) . 


. 
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When  the  user  begins  a  block  definition  with  a  call  to 
subroutine  BLOCK  (Appendix  I) ,  the  BLT  element  for  that 
block  is  leaded  with  the  address  contained  in  POINTER  and 
the  high  order  byte  is  set  to  zero.  The  BLT  displacement  is 
stored  in  the  halfword  pointed  to  by  CODE ,  and  CODE  is 
incremented  by  two.  The  high-order  byte  of  the  address 
contained  in  POINTER  is  set  to  zero,  and  the  address 
contained  in  POINTER  is  decremented  by  four.  BLKSP  is 
decremented  by  six.  CODE  is  stored  at  the  address  contained 
in  POINTER  and  the  high-order  byte  at  this  address  is  set  to 
hexadecimal  01  to  indicate  the  last  pointer.  As  the  user 
calls  the  code  generation  routines  (Appendix  I)  to  build  a 
block,  GRID  code  is  inserted  at  the  address  contained  in 
CODE,  CODE  is  incremented  and  ELKSP  is  decremented.  The 
location  pointed  to  by  the  last  Elock  File  pointer  is  set  to 
the  address  contained  in  CODE. 


When  a  block  is  required,  the  address  of  the  Block  File 
pointer  for  that  block  is  found  by  referencing  the  BLT  with 
the  BLT  displacement  for  that  block  (block  number  times 
four) .  The  desired  block  is  the  area  bounded  by  the  address 
contained  in  the  Block  File  pointer  for  that  block  and  the 
address  contained  in  the  pointer  immediately  above  the  Block 
File  pointer  for  that  block. 


If  a 

block 

definition  is  deleted  by 

a  call  to  DEL BLK 

(Appendix  I) 

,  the 

high  order  byte  in 

the  BLT 

element  and  in 

the  Block 

File 

pointer  for  the 

block 

is  flagged  with 

hexadecimal 

80  to 

indicate  garbage. 

If  the 

block  is  then 
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redefined,  the  BLT  element  fcr  this  block  is  updated 
accordingly,  but  the  old  pointer  is  not  changed.  A  new 
Block  File  pointer  is  established.  The  pointers  are  kept  in 
order  and  are  only  changed  when  garbage  collection  is 
performed  by  GARBAGE . 


requi 

count 

Elock 

Block 

File 

searc 

Elock 

saved 

searc 

delim 

next 

good 

Elock 

block 

displ 

as  a 

conti 

ELK  SP 


Garbage  collection  is  performed  when  more  space  is 
red  than  is  available  in  the  Elock  File.  BLKSP  is  the 
er  maintained  to  keep  track  of  available  space  in  the 
File.  Garbage  collection  begins  at  the  top  of  the 
File  by  testing  the  high  order  byte  of  the  first  Block 
pointer  that  is  flagged  to  indicate  garbage.  This 
h  continues  with  the  next  pointer  (1  word  lower  in  the 
File).  When  garbage  is  encountered,  the  address  is 
and  the  scan  of  the  Block  File  pointers  continues,  now 
hing  for  a  pointer  that  is  not  flagged.  The  area 
ited  by  the  first  pointer  found  to  be  flagged  and  the 
pointer  which  was  not  flagged  is  an  area  into  which 
code  can  be  moved,  replacing  the  garbage.  Obsolete 
File  pointers  are  updated.  The  BIT  elements  for 


s  which  were 

moved  are 

updated  using  the 

ELT 

acement  stored 

in  the  first 

half - 

word  of  the  block 

code 

d isplacement 

to  locate 

the 

BLT  element.  The 

scan 

nues  until  all 

garbage  has 

been 

deleted,  then 

CODE, 

and  POINTER  are  updated. 


Space  for  the  Block  File  is  obtained  at  execution  time 
and  can  be  easily  changed  by  modifying  the  size  parameter, 
ELKSZ.  This  method  allows  the  user  to  expand  the  Block  File 
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if  necessary.  Since  space  is  not  allocated  separately  to 
Elock  File  pointers  and  Block  code,  the  data  structure  is 
suitable  for  all  types  of  program,  whether  there  are  to  be 
many  small  blocks  or  a  few  large  blocks. 

An  example  is  shown  below  of  how  this  structure  can  be 
expanded  to  encompass  the  nested  block  feature  inplemented 
by  Huen  (1969).  Other  expansions  to  the  Block  File  could  be 
made  similarly  to  incorporate  nested  blocks. 

The  nested  block  feature  allows  the  user  of  GRIDSUB  to 
include  a  previously  defined  block  within  the  block 
currently  being  defined.  A  nested  block  is  indicated  when  a 
pointer  in  the  Block  File  begins  with  hexadecimal  40.  The 
address  portion  of  this  pointer  indicates  the  halfword 
immediately  following  the  code  that  so  far  comprises  the 
block  being  defined.  This  halfword  contains  the  BIT 
displacement  for  the  block  that  is  being  nested.  A  block 
definition  is  considered  ccnplete  when  a  pointer  is 
encountered  that  begins  with  hexadecimal  00  or  01.  Pointers 
that  begin  with  hexadecimal  80  are  used  as  delimiters  to 
separate  code  that  has  been  deleted  from  code  that  has  not 
been  deleted.  'Deleted*  code  is  code  that  is  no  longer 
used.  For  example,  if  the  definition  of  a  block  is  deleted 
using  subroutine  DELBLK ,  then  that  code  is  deleted  and  it  is 
possible  to  redefine  that  block.  The  major  advantage  of 
having  nested  blocks  described  in  this  manner  is  the  savina 
in  space  obtained  by  having  the  code  for  a  block,  whether 
nested  or  not  nested,  stored  only  once  in  the  Block  File. 


. 

- 

% 

■ 


BLOCK  LOCATION  TABLE 


50 


o 

O  o  <H 

cn 


UJ 


o 

o 

_J 

CO 

I 

tr\ 

UJ 

C£ 

ZD 

(T 

u. 


OJ 


on 


51 


The  importance  of  adequate,  flexible,  and  extensible 
data  structures  cannot  be  over-emphasized  in  the  development 
of  good  software. 

3.5  Documentation  for  GRIDSUB 

The  three  basic  pieces  of  documentation  described  in 
Chapter  II  are  discussed  in  the  following  sub-sections  as 
they  apply  to  the  new  GRIDSUB  system.  At  the  present  time 
the  User’s  Manual  is  in  machine  readable  form  and  is 
produced  using  a  text  formatting  package.  Work  is  about  to 
begin  on  producing  the  internal  logic  documentation  in  the 
same  manner. 

3.5.1  Software  Specification 

Unfortunately,  GRIDSUB  was  the  first  very  large 
software  project  undertaken  by  the  author.  When  the  project 
was  begun,  it  was  felt  that  a  finished  product  would  be 
achieved  mere  guickly  by  not  writing  a  software 
specification. 

Initially,  the  system  was  broken  into  three  more 
manageable  pieces.  These  were  block  storage,  display  file 
management  and  message  decoding.  A  data  structure  was 

proposed  for  block  storage  and  programming  began.  The 
procedure  was  very  similar  to  the  method  suggested  for 
a  software  specification,  except  that  instead  of 
describing  the  modules  for  GRIDSUB,  they  were 
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programmed.  As  development  progre 
data  structure  became  appare 
reprogramming  was  required.  In  the 
Chapter,  a  description  of  the 
functional  specification  for  severa 
If  this  had  been  done  before 
recoding  could  have  been  avoided. 


ssed,  deficiencies  in  the 
nt  and  considerable 


previous 

section  of 

this 

Block  Fi 

le 

and  a 

brief 

1  modules 

has 

been  g 

iven . 

programming 

began. 

much 

For  example,  the  original  format  for  the  Block  File 
structure  was  adequate  for  storing  the  blocks  as  defined  by 
the  user.  However,  the  data  structure  was  organized  in  such 
a  way  that  garbage  collection  was  impossible.  Space  made 
available  by  deleting  blocks  was  net  reusable.  The  user 
also  could  only  define  a  maximum  of  one  hundred  blocks. 

A  functional  specification  should  have  been  written  for 
the  Block  File  garbage  collector.  As  a  result,  the  data 
structure  had  to  be  redesigned  and  the  programming  redone. 

The  material  presented  in  Section  3.4  of  this  thesis 
may  be  considered  as  one  possible  way  to  write  a  software 
specification.  If  this  approach  had  been  taken,  system 
implementation  would  have  been  realized  much  sooner. 


3.5.2  Internal  Logic  Documentation 

GRID  SUE  is  a  large  software  system,  requiring  about 
12,000  source  program  cards.  Cue  to  this  large  size,  the 
internal  logic  documentation  for  one  module  only  of  GRIDSUB 
is  given  (Appendix  IV) . 
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An  overview  of  the  GRIDSUE  system  is  shown  in  Appendix 
V.  ihe  material  in  this  Appendix  is  intended  to  be  the 
‘black-box'  description  of  the  system  mentioned  in  Section 
2.5.2.  This  general  description  is  intended  to  provide  the 
necessary  information  about  the  system  from  which  the  more 
detailed  description  of  individual  modules  may  be  approached 
with  more  insight. 


Appendix  IV 

is  an 

example  of  the 

program 

logic 

documentation  for 

a  single 

module.  The  three 

basic 

pieces 

of  information 

needed 

for  complete 

internal 

logic 

documentation  were  mentioned  in  Section  2.5.2.  These  are: 

1.  Written  documentation  describing  the  module. 

2.  Flow  charts  for  the  module. 

3.  A  source  listing  for  the  module. 

The  example  given  in  Appendix  IV  is  for  a  very  small 
module,  but  even  for  such  a  small  module  a  considerable 
amount  of  work  is  reguired  for  complete  documentation.  When 
planning  a  system,  the  work  required  for  complete 
documentation  should  not  be  under-estimated. 


3.5.3  User ' s  Guide 

Since  GRIDSUB  is  a  user-oriented  software  package, 
considerable  effort  was  needed  to  prepare  a  suitable 
reference  for  the  user.  The  User's  Guide,  Computer  Graphics 
for  the  Application  Programmer  (Jackson  1972), 
in  part  within  this  thesis  (Appendix  I) . 


is 


included 
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Ihe  Table  cf  Contents  for  the  User's  Guide  is  shown  in 
Figure  3-3.  The  manual  is  written  in  sections  so  that  a 
change  to  the  system  should  result  in  a  change  only  to 
isolated  sections  within  the  documentation.  This  greatly 
simplifies  the  problem  of  maintaining  ’current* 
documentation.  At  this  time,  the  GRIDSUE  User's  Manual  is 
produced  with  the  aid  of  the  text  formatting  package. 
Section  3  of  the  User's  Guide  is  included  as  Appendix  I  to 
provide  the  reader  with  a  sample  of  user  documentation  as 
well  as  a  description  of  the  GRIDSUE  software. 

The  format  of  the  table  of  contents  (Figure  3-4)  may  be 
summarized  as  follows: 

1.  General  Introduction 

2.  Hardware  Description 

3.  Software  Description 

4.  Operating  System  Interfacing 

5.  Examples 

6.  Appendices 

These  six  parts  are  the  tasic  components  for  this  type 
of  user's  guides.  Not  all  sections  are  applicable  for  all 
software.  It  is  hoped  that  the  six  general  headings  can 
serve  as  a  guide  for  the  preparation  cf  most  user  oriented 
documentation  describing  hardware/software  packages  similar 


to  GRIDSUB 
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CHAPTER  IV 
CONCLUSION 


At  the  present  time,  the  art  of  software  design  is  not 
at  a  comparable  level  with  other  areas  in  computing  science. 
Ihe  main  reason  for  shortcomings  in  software  design  is  the 
lack  of  generally  accepted  principles  that  may  be  used 
effectively  in  the  construction  of  good  software.  The 
intention  in  this  thesis  has  been  tc  formulate  and  discuss 
several  general  design  principles,  and  illustrate  their 
importance  by  reference  to  a  software  package  implemented  by 
the  author.  In  summary,  the  principles  discussed  in  this 
thesis  are  briefly  reviewed  below. 

Modularity  is  the  dividirg  of  a  program  into  separate, 
clearly  defined  units  that  are  mere  manageable  tc  program 
and  debug.  Modularity  makes  possible  the  use  of  overlay 
structures  and  the  creation  of  program  libraries  to  allow 
mere  efficient  use  of  resources.  The  clear  definition  of 
modules  as  parts  of  a  total  system  readily  facilitates  group 
development  in  large  software  projects. 

Standardization  makes  the  job  of  program  maintenance 
and  program  writing  much  simpler.  Ey  adhering  to  a  standard 
linkage  one  module  may  be  readily  substituted  for  another. 
The  programmer,  by  following  standard  practices  such  as  the 
use  of  symbolic  addressing  and  straightforward  well 
commented  code,  can  simplify  the  job  of  program  maintenance 
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which  may  be  the  responsiblity  of  other  programmers.  By 
making  as  many  modules  as  possible  operating  system- 
independent,  an  operating  system  change  will  reguire  that 
cnly  a  minumum  number  of  modules  be  modified. 
Standardization  of  program  documentation  can  greatly 
simplify  the  problems  of  searching  for  information. 

Efficiency  and  stability  may  be  built  into  a  system 
without  one  extensively  interferring  with  the  other  by 
constructing  a  multi-level  program  structure.  The  modules 
at  the  upper  levels  can  provide  extensive  error  checking 
while  the  modules  at  the  lower  levels  are  special  purpose 
routines  that  require  little  or  no  error  checking.  The 
routines  at  this  lower  level  can  be  made  available  for  the 
more  sophisticated  user  who  seeks  efficiency. 

Flexibility  and  extensibility  are  an  important  part  of 
good  software.  Ey  giving  extra  thought  to  the  way  in  which 
system  data  structures  are  to  be  organized,  it  should  be 
possible  to  build  a  system  that  is  flexible  and  open  to  many 
possible  extensions.  The  added  work  involved  in  developing 
these  data  structures  is  more  than  compensated  for  by  the 
saving  made  if  less  adequate  data  structures  were  used  and  a 
new  system  had  to  be  written  at  a  later  date  due  to  of  a 
lack  of  flexiblity. 

Complete  documentation  consists  of  three  parts.  The 
software  specification  is  written  before  the  programming 
begins  and  serves  as  a  blueprint  for  the  software.  The 
effort  put  into  a  good  specification  is  well  worth-while 


’ 

* 


60 


since  it  will  probably  prevent  seme  over-looked  item  forcing 
major  redesign  after  programming  has  begun.  The  Internal 
logic  Manual  is  a  necessary  document  if  other  people  are  to 
understand,  maintain  and  modify  the  software.  Even  the 
designer  begins  to  forget  how  his  software  works.  The 
User’s  Guide  provides  the  users  of  the  software  with  the 
necessary  information  to  utilize  the  system. 


The  principles  discussed  in  this  thesis  are  not  a 
complete  list  of  software  design  principles.  Much  more 
research  needs  to  be  devoted  to  the  formulation  of  general 
software  design  principles  that  are  practical  and  usable. 
For  example,  the  section  on  documentation  in  this  thesis 
discussed  several  important  aspects  of  documentation. 
However,  it  was  beyond  the  scope  of  this  thesis  to  develop  a 
general-purpose  format  for  the  documentation  of  software 
packages  of  all  types.  This  is  one  of  the  many  things 
needed  to  advance  the  art  of  software  design.  Standards 
have  been  laid  down  and  widely  accepted  for  the  definition 
of  the  FORTRAN  language.  The  same  should  be  done  for  a 
method  of  software  documentation  that  could  become  as  widely 
accepted  as  the  definition  of  the  FORTRAN  language.  If  such 
a  standard  could  be  accepted  and  used,  the  problem  of 
communication  between  software  engineers  could  be  reduced 
greatly.  As  a  result,  there  would  probably  be  much  less 
duplication  of  software  packages,  which  could  release 
enormous  resources,  both  in  money  and  manpower,  for  the 
development  of  new  software. 
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The  area  cf  documentation  is  just  one  example  of  how 
much  more  work  is  required  so  that  a  complete  set  of  design 
software  design  principles  could  be  formulated  and 
eventually  beccme  the  accepted  standard  for  good  software 
design. 

The  formulation  and  general  acceptance  of  software 
design  principles  should  greatly  improve  the  quality  and 
"life-span"  cf  software  packages. 
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APPENDIX  I 

3 .  FORTRAN  Subroutines  -  The  GRID SUB  Package 

3 . 1  Introductory  Description 

A  package  of  assembler  language  routines  (GRIDSUB) , 
callable  frcm  a  FORTRAN  program,  is  available  for  defining, 
displaying,  and  modifying  graphic  elements,  and  for 
controlling  communication  between  the  FORTRAN  program  and 
the  display  user.  Concise  definitions  of  these  routines  are 
given  in  Secticn  3.2.  The  routines  are  classified  according 
to  their  functions: 

(a)  Block  handling 

(b)  Definition  of  graphic  elements 

(c)  Block  display 

(d)  Display  modification 

(e)  Transmission  and  message  decoding 

(f)  Data  conversion. 

Examples  of  use  of  the  routines  are  given  in  Section  5. 

Any  picture  is  defined  as  a  set  of  discrete  components 
called  blocks,  each  with  an  identifying  number  in  the  range 
1-511.  A  block  definition  is  opened  by  a  call  to  the 
subroutine  ELOCK,  and  closed  by  a  call  to  ENDBLK .  The 
content  of  a  block  is  defined  by  calls  to  the  routines: 

VECTOR,  which  defines  a  line, 

DLINE ,  which  defines  a  series  of  connected  line 
segments , 
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MOVE,  which  defines  a 
line  being  drawn, 
POINTX,  which  defines 
TEXT,  which  defines  a 
ch  ar  acters . 


positional  move  without 

a  point, 

string  of  alphanumeric 


any 


The  block  definition  is  added  to  a  file  called  the 
Flock  File,  No  display  of  the  block  can  take  place  until  a 
EISPLY  call  for  that  block  is  given,  a  DISPIY  call  must 
include  the  block’s  identification  NUMBER.  The  block  is  the 
basic  component  for  display  and  for  light  pen  detection.  For 
example,  where  a  number  of  graphs  are  to  be  displayed,  each 
with  different  axes,  one  graph  with  its  axes  could 
constitute  a  block.  On  the  other  hand,  if  several  graphs  are 


to  be  displaye 

d 

all  with 

the 

same 

axes,  the 

axes 

could 

constitute  a  s 

in 

gle  separate  block. 

The  blcc 

k 

number 

can 

also 

be  used  to 

distin 

guish 

elements  picke 

d 

with  the 

light 

pen. 

For  example. 

where 

there 

are  a  number  o 

f 

command 

words 

to  be 

displayed 

which 

must , 

after  a  light  pen  pick,  be  distinguishable  from  one  another, 
each  could  be  defined  as  a  separate  block.  On  the  other 
hand,  the  words  could  all  be  defined  within  a  single  block, 
and  the  distinction  between  them  made  on  the  basis  of  their 
position  or  their  ID^ 


Each  blcck  has  an  origin, 
begins.  The  programmer  can 
elements  within  the  definition 


the  point  at 
define  the 
in  either  of 


which  definition 
coordinates  of 
two  modes: 


R  1 

' 

;  -21 
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Absolute 


(with  respect  to  the 


block  origin) 


Relative 
completing  the 

Selection 
actual  display 
DISPIY.  The  blc 
identification 
if  required, 
positions  on  th 
Absolute  sere 
position  on  the 


(with  respect  to 
previous  element  of 

from  the  block  file 
is  effected  with 
ck  is  referenced  by 
ID  is  added;  the  sam 
with  different  ID  * 
e  screen  with  IE*s  i 
en  coordinates  are 
screen  of  the  blcck 


the 

bea 

m  posi 

tion 

after 

the 

d 

efi 

nition) 

• 

of 

a 

defined 

block 

for 

a 

ca 

11 

to  the 

subroutine 

its 

numb 

er,  and  a 

copy 

e  bio 

ck 

can  be 

displayed , 

s 

at 

u 

p  to  64 

diff 

erent 

n 

th 

e 

range 

0  to 

63. 

u 

se 

d 

to  ind 

icate 

the 

origin . 


The  DISPLY  call  causes  the  transfer  of  block 
definitions  from  the  Block  File  tc  a  buffer.  The  picture  to 
be  displayed  can  thus  be  assembled  with  a  series  of  DISFLY 
calls.  However  the  picture  itself  does  not  appear  on  the 
screen  until  the  tuff er  (s)  are  transferred  to  the  Display 
File  in  GRID  with  a  TRANMT  call. 


The  TRANMT  subroutine  sends  the  buffer(s)  and  any 


modif 

ications  which 

have 

been 

made  to 

the 

Di 

splay  File 

to 

GRIE, 

and  put 

the 

user 1 

s  pro 

gram  int 

o  the  ” 

wait”  state 

.  No 

time 

is  charged 

agai 

nst 

the 

pregram 

until 

a  message 

is 

recei 

ved  frem 

the 

display  op 

erator . 

The 

ope 

rator  can  s 

tudy 

the  d 

isplayed  image. 

and 

indie 

ate  the 

desired 

actions 

with 

the 

light  pen 

and 

key 

board 

,  norma 

iiy 

one 

or  more  of 

the 

actio 

ns  specified  in 

Sect 

ions 

2.3,  2 

.4 

as 

being  allowed 

under 

the  MULT II 

2  ANK 

super 

visor 

• 
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When  the 

operat 

or  presses 

the  SEND  key  tc  indicate 

”end 

of  message”. 

the 

applicat 

icn  program  resumes  at 

the 

statement  following 

the  CALL 

TBANMT.  At  this  point. 

the 

operators  message 

may  be 

dec 

cded  by  using  special  deco 

ding 

routines : 

DLPEN 

(to 

check 

for 

light  pen  picks) 

DFKEY 

(to 

check 

for 

status/function  keys) 

D ALPHA 

(to 

check 

for 

alpha  characters) 

DVECT 

(to 

check 

for 

vectors) 

DPOINT 

(to 

check 

for 

points) 

DEND 

(to 

check 

for 

end-cf-message) 

A  call 

message  com 
expected.  If 
statement  n 
time,  parame 
cf  the  messa 

Process 
almost  cert 
required.  Ev 
made  a  mis 
displayed . 

Blocks 

call.  A  po 
subroutine . 


to  any  of  these  routines  allows  a  specified 
ponent  to  be  checked  tc  see  if  it  is  of  the  type 
the  type  is  as  expected,  a  branch  is  made  to  a 


umber 

given  as  an 

argumen 

t,  and,  at  the  same 

ters  given  in  the  CALL  are  se 

t  with  the  contents 

ge  component. 

ing  of 

the  message  from  the  G 

RID  operator  will 

ainly 

show  that  a 

change 

to  the  picture  is 

en  if , 

as  will  often 

happen. 

the  operator  has 

take , 

a  diagnostic 

message 

will  have  to  be 

can  be 

added  to  the 

picture 

with  the  DISFLY 

si tion 

can  be  changed  with  a 

call  to  the  MOVEBK 

Elocks 

can  be  erased 

with  the 

ERSBK  subroutine. 

if  O'  l  -  | 
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Erased  blocks  can  be  made  visible  again  with  the  reset 
routine,  RSTEK. 

ERSBK  and  RSTBK  calls  do  not  effect  the  Block  File,  nor 
do  they  cause  removal  of  the  definitions  from  the  Display 
File  (in  the  GRID  core).  They  are  therefore  most  suitable 
for  temporary  erasure.  To  conserve  space  in  the  GFID  core, 
it  may  be  advisable  to  use  the  FFEEEK  call,  which  deletes 
the  definition  frcm  the  Display  File  while  retaining  it  in 
the  Block  File.  DELID  will  destroy  a  copy  of  the  block, 
again  helping  to  conserve  space  in  the  Display  File.  With 
either  FREEEK  or  DELID,  the  block  or  copy  can  be  restored 
with  a  DISPLX  call.  However,  where  a  block  definition  is  no 
longer  reguired-for  example,  initial  messages  to  the 
operator  are  redundant  after  his  first  response  -  the 
subroutine  DFLELK  may  be  used  to  destroy  the  block 
definition  in  the  Block  File,  as  well  as  in  the  Display 
File.  Destruction  of  unwanted  block  definitions  helps  to 
conserve  space  in  the  Block  File. 

Displayed  blocks  are  normally  light-pen  detectable.  It 
may  be  necessary,  for  example  if  blocks  are  overlaid  on  the 
screen,  to  vary  the  detectability  of  one  or  more  copies  of  a 
block.  This  can  be  done  with  a  call  to  the  subroutine  LP. 

Subroutine  TEXT  allows  definition  of  blocks  including 
alphanumeric  characters.  However,  the  programmer  may  wish  to 
display  a  result  of  a  computation,  in  which  case  conversion 
frcm  INTEGER  or  REAL  format  to  character  format  is  necessary 


. 
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before  TEXT  can  be  used.  Conversely,  data  i 
terminal  is  in  character  form,  and  must 
INTEGER  or  REAL  before  arithmetic  can  be  done 
listed  below,  to  save  space,  make  use  of  the 
subroutines  which  are  part  of  the  FORTRA 
routines. 


nput  from  the 
be  converted  to 
.  The  routines 
data  conversion 
N  formatted  I/O 


CHRFLT 
INTCVT 
FITCH  R 
INTCHR 
DMPHEX 


(character  to  REAL) 

(character  to  INTEGER) 

(REAL  to  character) 

(INTEGER  to  character) 

(internal  form  to  hexadecimal  character) 


Finally,  a  dump  routine  is  available 
hexadecimal,  the  contents  of  all  files 
GRIESUB.  This  routine  may  be  useful  if 
difficult.  The  routine  is  called  DUMPIT. 


for  printing,  in 
and  tables  used  by 
debugging  proves 


3 . 2  GRID SUE  Specifications 

3.2.1  Error  Handling 

Errors  detected  by  GRIDSUB  result  in  an  error  message 


cn  SPRINT 


. 


. 
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3.2*2  Block  Definition  Subroutines 

(1)  BLOCK  J NUMBER^ 


Parameter  NUMBER:  Mode  INTEGER1 ;  Range  1<NUMBER<511 


Function 


The  definition  of  a  block  is  opened,  and 
henceforth  can  be  referred  to  by  the  value  of 
NUMBER . 


Possible  Errors 

1.  Block  NUMBER  is  not  in  range  1  to  511. 

2.  Block  NUMBER  is  defined. 

3.  Previous  block  unended. 

4.  Block  file  is  full. 


(2)  ENDB!K 

Function 

The  definition  of  a  block  is  closed.  Each 
definition  must  be  closed  with  a  call  to 
ENCBIK  before  another  definition  is  opened. 


i Mode  INTEGER  means  INTEGER*4  hereafter  unless 
specified . 


otherwise 
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Possible  Errors 

1.  A  block  is  not  open. 

2.  Empty  block,  blcck  not  defined. 

3.  Block  File  full 

3.2.3  Graphic  Element  Generation 

(1)  MOVE  JREIEMj,  Xx  II 


Parameters  RELBM: 


Mode  LOGICAL* 1 


X ,  Y :  Mode  INTEGER;  Range  - 1 02 3<X , Y<  1 023 


Function 

Within  a  block  definition,  the  beam  is  moved 
without  a  line  being  drawn  to  a  position: 

(X'+X,  Y'+Y)  if  RELBM  is  .TRUE., 
or  (X,Y)  if  RELBM  IS  .FALSE.,  if  the  previous 
team  position  was  (X1,  Y')  and  where  all 

coordinates  are  taken  relative  to  the  block 
origin. 


Possible  Errors 

1.  Block  not  opened 

2.  X  or  Y  increment 

3.  Elock  File  full. 


not  in  range  -1023  to  1023. 


(2) 


VECTOR  JRELBM ,  Xx  Xx  BLINKx  DASH) 
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(3) 


Parameters  RELBM :  Mode  L0GICAL*1 

X ,  Y :  Mode  INTEGER;  Range  -  1023<X , Y< 1023 
BLINK:  Mode  LOGICAL*! 

DASH  :  Mode  LOGICAL* 1 

Function 

Within  a  block  definition,  a  line  is  defined 
from  the  previous  beam  position  to 
(X'+X,  Y'+Y)  if  RELBM  is  TRUE . 

(X ,  Y)  if  RELBM  is  FALSF 
where  the  previous  beam  position  was  (X'jY') 
and  where  all  coordinates  are  taken  relative 
to  the  block  origin.  The  lines  will  be  shown 
blinking  if  BLINK  is  .TRUE.,  and  dashed  if 
DASH  is  .TRUE. 

Possible  Errors 

1.  Block  not  opened. 

2.  X  or  Y  not  in  range  -1023  to  1023. 

3.  Block  File  full. 

DLINJ  1BELBMX  RELBMlx  Mx  Mx  lx  BLINKx  PASH}. 

Parameters  RELBM:  Mode  LOGICAL* 1 

RELBM 1 :  Mode  LOGICAL*1 

AX , A Y :  Mode  INTEGER*2  vector f Dimension=N 


N: 


Mode  INTEGER 


. 
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Function 

AX  and  AY  are  arrays  of  at  least  N  elements. 
A  line  is  defined  through  each  of  the  N 
points  represented  by  (AX  (T) ,  AY  (I)),  I 
1,N.  The  line  begins  at  the  point  (AX(1), 
AY  (1))  . 

If  REIBM  IS  .TRUE.  ,  (AX  (1)  ,  AY  (1 )  )  is 
taken  to  be  the  coordinates  relative  to  the 
beam  position  before  DLINE  vas  called. 

If  REIBM  is  .  F  AISE .  ,  (AX(1),  AY(1))  is 

taken  to  be  the  coordinates  relative  to  the 
block  origin. 

If  REIBM  1  is  .TRUE.,  (AX(I),  AY  (I)  )  , 
2<I<N,  are  taken  tc  be  relative  to  the  last 
beam  position,  that  is  as  increments  X  ,  Y  . 

If  RELBM1  is  .FALSE.,  (AX  (I)  ,  AY  (I) )  , 
2<I<N,  are  taken  to  be  relative  to  the  block 
origin . 

The  line  will  be  shown  blinking  if  BLINK 
is  .TRUE.,  and  dashed  if  DASH  is  .TRUE. 


. 
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Possible  Errors 

1.  Block  not  opened. 

2.  X  or  Y  not  in  range  -1023  to  1023. 

3.  Block  File  full. 

(4)  POINT X  Xx  Yx  BLINK]_ 

Parameters  RELBM :  Mode  LOGICAL*  1 

X ,  Y  :  Mode  INTEGER ,  Range  - 1 02 3<X , Y< 1 023 

Function 

Within  a  block  definition,  a  point  is  defined 
at  (X'+X,  Y'+Y)  if  RELBM  is  .TRUE.  or  (X,Y) 
if  RELBM  is  .FALSE.  where  (X«,Y')  is  the 
previous  beam  position,  and  all  coordinates 
are  taken  relative  to  the  block  origin.  The 
point  will  be  shown  blinking  if  BLINK  is 
.TRUE. 

Possible  Errors 

1.  BLOCK  not  opened. 

2.  X  or  Y  not  in  range  -1023  to  1023. 

3.  Block  File  full. 


- 


76 


(5)  TEXT  JRELBMx  Xx  Yx 


Nx  CHAFX 


LARGEX  BLINK]. 


Parameters  RELB  M :  Mode  LCGICAL*1 


X  , Y  :  Mode  INTEGER;  Ranqe  -  1 02 3<X , Y< 1 023 


Mode  INTEGER;  Range  1 < | N | < 86 


CHAR 


Mode:  Any  scalar  cr  array,  or 


Hollerith  or  literal  string 


LARGE 


Mode  LOGIC  AL* 1 


BLINK 


Mode  LCGIC AL* 1 


Function 


Within  a  block  definition,  a  string  of  |N| 
characters  beginning  at  CHAR  (or  as  the 
Hollerith  or  literal  string)  is  defined.  The 
position  of  the  center  of  the  first  character 
is  specified  by  RELBM ,  X,  Y.  If  N  is 
positive,  the  characters  are  defined  in  the 
+  X  direction;  if  N  is  negative,  the 
characters  are  defined  in  the  +Y  direction. 

The  GRID  character  set  differs  slightly 
from  that  of  the  029  punch  (see  Appendix  I) . 

If  LARGE  is  .TRUE.,  characters  are 
approximately  13.6  (wide)  x  17.9  (high) 
raster  units,  with  spacing  of  16  raster  units 
between  centres  cf  successive  characters. 


•  » 


If  LARGE 


is 


FALSE 


characters  are 


-)  1 , 


■ 
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approxim 

atel  y 

10.7  (wide)  x  14.2 

(hioh) 

raster 

units. 

with  spacing  of  12 

raster 

units . 

Notes 

(1)  If,  on  display,  the  num 
greater  than  can  he  accom 
the  characters  will  "w 
advancing  to  a  new  line. 

(2)  After  definition  cf  a  c 

team  position  is  assumed 
of  the  (undisplayed) 
follow  the  last  symbol  of 
NC1Ej_  85  r  asters-1 

characters/line,  64  large 


her  of  characters  is 
modated  on  one  line, 
rap-around"  without 

haracter  string,  the 
to  be  at  the  centre 
symbol  which  would 
the  string, 
inch,  86  small 
characters/line . 


Possible  Errors 

1.  Block  not  opened. 

2.  X  or  Y  not  in  range  -1023  to  1023 

3.  Number  of  characters  not  in  range  |1|  to  | 86 | . 


4. 


Block  File  full 


. 


IDY  J3D1 


Parameter  ID: 


Mode  INTEGER;  Range  0<ID<63 


Function 


The  value  of  the  copy  identifier  is  set  to 
the  value  given  for  ID  (see  the  DISPLY 
routine) .  The  value  of  ID  returned  after  a 
light  pen  hit  on  the  section  of  the  block 
defined  after  the  CALI  IDY  will  have  the 
value  defined  in  the  CALI  IDY.  (see  the 
decoding  routines) . 


Possible  Error sj_ 

1 .  Block  not  opened. 

2.  ID  not  in  range  0  to  63. 

3.  Block  File  full. 

Note 

When  issuing  calls  such  as  DELID,  LP,  MCVEBK  etc.,  the 
ID  GIVEN  SHOULD  BE  THAT  used  in  the  DISPLY  call. 


.2.4  Elock  Display 

DISPLY  (NUMBER^  IDX  ABSXx  AB SY) 


Parameters 


NUMBER: 


Mode  INTEGER;  Range 


' 
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1<NUMEER<51 1 

ID:  Mode  INTEGER;  Range  0<ID<63 

ABSX,  ABXY :  Mode  INTEGER;  Range 

0<ABSX,  AESY< 1 023 


Function 


A  previously  defined  block  designated  by 
NUMBER  is  transferred  to  the  Display  File  for 
display.  It  will  appear  with  its  origin  at 
( AE  SX , AB  S Y) .  The  copy  of  the  block  will  be 
given  the  identification  ID. 


Note  The  values  of  ABSX  and  ABSY  must  be  chosen  so 
that  no  part  of  the  block  will  be  outside  the 
screen  limits. 


Possible  Errors 


1.  Block  NUMBER  not  in  range  1  to  511. 

2.  ID  not  in  range  0  tc  63. 

3.  AESX  or  ABSY  not  in  range  0  to  1023. 

4.  Block  to  be  displayed  is  not  defined. 

5.  Block  previously  displayed  with  this  ID  - 
not  displayed. 

6.  Buffers  full  -  block  not  displayed. 

7.  Bank  Tables  full  -  block  not  displayed. 

8.  Display  file  full  -  block  not  displayed. 


block 
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3.2.5  Display  Mod  if  jkrat  icn 
(1)  MOVEEK  JNUMBERx  IDa  ABSXx  ABSY]_ 


Parameters  NUMBER: 

Mode 

INTEGER; 

Range 

1  <NUMBER<5 1 1 

ID: 

Mode 

INTEGER; 

Range 

0<ID<63 

ABS X  : 

Mode 

INTEGER; 

Range 

0< ABSX<  10  23 

ABSY: 

Mode 

INTEGER; 

Range 

0<ABSY<  1023 

Function 


A  displayed 

copy  cf 

a  block 

designated 

by 

NUMBER  and 

I D  is 

moved  to 

a  new  position 

( ABSX ,  ABSY) 

,  where 

ABSX  and 

ABSY  are 

in 

absolute  scr 

een  ccor 

dinates . 

Errors 

1.  Block  number  not  in  range  1  to  511. 

2.  ID  not  in  range  0  to  63. 

3.  AESX  or  ABSY  not  in  range  0  to  1023. 

a.  Block  with  specified  ID  is  not  currently  being 
displayed . 

5.  Queue  full  -  move  not  done.1 


(2) 


ERSBK  _£NUMBER}_ 

Parameter  NUMBER:  Mode  INTEGER ;  Range  1<NUMBER<511 


Appendix  III 


j  V.  Lx;: 
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(3) 


Function 


All  copies  of  the  block  designated  by  NUMBER 
are  erased  from  the  screen.  The  block 
definition  remains  in  GRID  core,  and  the 
block  can  be  made  visible  again  with  the 
RSTBK  subroutine. 

Possible  errors 

1.  Block  number  not  in  range  1  to  511. 

2.  Blcck  to  be  erased  is  not  displayed. 

3.  Queue  full  -  erases  not  complete.1 

RSTBK  J NUMBER^ 


Parameter  NUMBER:  Mode  INTEGER;  Range 


1<NUMBER<511 


Function 

Copies  of  block  NUMBER,  previously  erased  by 
an  ERSBK  call,  are  made  visible  again. 

Possible  Errors 

1.  Block  number  not  in  range  1  to  511. 

2.  Block  to  be  restored  is  net  erased. 

3.  Queue  full  -  restores  not  complete.1 


(4) 


FREE  EK  JNUMBER}. 


. 
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Parameter  NUMBER:  Mode  INTEGER;  Range  1<NUMBER<511 


Function 


Block 

NUMBER 

is 

removed 

from  the 

Display 

File . 

All 

copie 

s  will 

disappear 

from 

the 

screen 

.  The 

block 

can  be 

restored 

only 

by 

another  DISPLY  call. 


Possible  Errors 


1 . 
2. 
3. 


Block  number  not  in  range  1  to  511. 
Block  to  be  freed  is  net  displayed. 
Queue  full  -  frees  not  complete.1 


Note  ERSBK  and  FREEBK : 


FRSBK  is  faster  and  more 
FREEBK  releases  space  in 


convenient  than  FREEBK. 
the  Display  File. 


(5)  CEL ID  i NUMBER^  ID1 


Parameters 

NUMBER : 

Mode 

INTEGER ; 

Range 

1<  NUMBERS  5 1 1 

ID: 

Mode 

INTEGER  ; 

Range 

0<ID<63 

Function 


The 

copy 

ID  of 

block 

NUMBER 

is  deleted  from 

the 

Display  File. 

The 

copy 

will  disappear 

from 

the 

screen 

.  It  c 

an  be 

restored  only  by 

■ 
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another  DISPLY  call. 

Possible  Errors 

1.  Block  number  not  in  range  1  to  511. 

2.  IE  not  in  range  0  to  63. 

3.  Copy  of  block  to  be  deleted  is  not  displayed. 

4.  Queue  full  -  block  not  deleted. 1 


(6)  DELBLK  J NUMBER). 

Parameter  NUMBER:  Mode  INTEGER;  Range  1<NUMBER<511 


Function 


All  informati 

on  concerning 

block  NUMBER  is 

deleted 

from 

the  Display 

File,  and  the 

Block 

File. 

NUMBER 

can  then 

be  used  in 

the 

definition  of  another  block. 


Possible  Errors 


1 . 
2. 

3. 

4. 


Block  number  not  in  range  1  to  511. 
Block  to  be  deleted  is  not  displayed. 
Queue  full  -  deletes  not  complete. 
Block  to  be  deleted  is  not  defined. 


(7) 


LP  JNUMEER^  I Ex  EEIECT1 


Appendix  III 
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Parameters  NUMBER:  Mode  INTEGER;  Fanae  1<NUMBER<511 

ID:  Mode  INTEGER;  Fanqe  0<ID<63 

DETECT:  Mode  L0GICAL*1 


Function 


A  displayed  copy  cf  a  block  is  detectable 
with  the  light  pen  unless  otherwise 
specified.  If  DETECT= . FALSE.  ,  copy  ID  of 
block  NUMBER  is  made  not  detectable.  If 
DETECT=. TRUE . ,  the  copy's  detectability  will 
be  restored. 


Possible  Errors 


1 . 

Block 

number 

not  in 

ra 

nge 

1  to 

511. 

A  -■  • 

Block 

ID 

not 

in  range 

0  to 

63. 

3. 

Block 

to 

be 

altered 

is 

not 

dis 

played. 

4. 

Queue 

full  - 

detectabi 

lity 

not 

altered. 1 

Note  Selective  detectability  may  be  necessary  if 
items  are  overlaid  on  the  screen. 

3.2.6  Transmission  and  Decoding  Routines 


(1) 


TRANMT 


^Appendix  III 


■ 


DLPEN 

DFKEY 

DALPHA 

DVECT 

DPOINT 

DENE 

Paramet 


The  buffer  (s)  are  transmitted  to  GRID  and  the 
picture  is  displayed  on  the  screen.  The 
FORTRAN  program  then  goes  into  the  wait  state 
until  a  message  is  received  from  the 
operator.  The  program  resumes  at  the 
statement  following  the  TRANMT  call. 

On  the  resumption,  the  FORTRAN  program  can 
decode  the  message  using  the  decoding 
routines  whose  descriptions  follow. 


(INTNO , 

IX, 

1 Y, 

TYPE, 

ID 

,  BLK , 

SN) 

(INTNO , 

STATUS, 

KEY, 

SN) 

(INTNO, 

IX, 

IY, 

NUM, 

MAX 

,  STRING,  SN) 

(INTNO, 

NUM 

,  MAX 

,  X, 

Yr 

SN) 

(INTNO, 

NUM 

,  MAX 

,  x. 

Y, 

SN) 

(INTO, 

SN) 

INTNO: 

Mode 

IN1EG 

ER; 

Range 

1 <INTNO<20 

M 

X 

IY: 

Mode 

INIEGER; 

Fange 

0<IX,IY<1023 

TYPE 

• 

• 

Mode 

INTEGER; 

Range 

0<TYPE<2 

ID: 

Mode 

INTEGER ; 

Range 

0<ID<63 

BIK: 

Mode 

INTEGER 

vector ; 

Dimension  8 

STATUS: 

Mode 

INTEGER ; 

Range 

1  <  ST ATUS< 1 5 

KEY: 

Mode 

INTEGER; 

Range 

- 1 <KEY<9 

NUM: 

Mode 

INTEGER ; 

Range 

1<NUMBER<MAX 

- 

- 
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MAX 1  Mode  INTEGER;  Range  1<MAX<43 
STRING:  Mode  INTEGER*2  vector.  Dimension 
MAXi 

X:  Mode  INTEGER*2  vector.  Dimension 


Y: 


SN: 


MAXi 

Mode  INTEGER*2  vector.  Dimension 
MAXi 

N  is  a  statement  number. 


Function 


A  check  is  made  to  see  if  the  i 
component  (i  specified  by  INTNC)  is  of  the 
type : 

(DLPEN) 

( DFKEY) 

haracters  (DALPHA) 
(EVECT) 
(DPOINT) 

(DEND) 

If  the  type  is  as  requested,  control  is 
transferred  to  the  statement  specified  by  n, 
with  values  supplied  for  the  appropriate 
parameters.  If  the  type  is  not  as  requested, 
control  is  transferred  to  the  followinq 
statement  (see  example  in  Section  5.1.2). 

Assuming  that  the  action  is  correctly 
queried,  then 


light 

pen 

pick 

function 

key 

string 

of 

alpha  c 

string 

of 

vectors 

string 

of 

points 

end  of 

message 

i M A X  chosen  at  the  discretion  of  the  programmer. 
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(i)  With  DIPENX 

IX,  IY  record  positional  information  for 
the  entity  detected. 

TYPE=0  if  a  point  was  picked, 

T YPE=  1  if  a  symbol  was  picked, 

TYPE=2  if  a  vector  was  picked. 

ID  is  set  with  the  value  given  to  the 
picked  block  with  a  DISPIY  call. 

BLK ,  which  must  be  dimensioned  as  BLK  ( 8)  , 
is  set  with  the  block  number  and  nested 
block  numbers  of  the  entity  picked  with 
the  pen.  (Currently  nested  blocks  are  not 
supported  so  all  elements  except  BLK  ( 1 ) 
are  zero) . 

BLK  ( 1 )  is  set  with  the  number  of  the 
outermost  block. 

BLK  (2)  is  set  with  the  number  of  the  first 
level  nested  block,  and  so  on.  Unused 
elements  in  BLK  will  be  set  to  zero. 

If,  as  would  be  most  usual,  what  has  been 
picked  was  not  nested  (by  an  ADDBLK) ,  then 
only  BLK  ( 1 )  is  set. 


(ii)  With  DFKEY 

STATUS  is  set  with  the  value  of  the  status 
key  setting. 

KEY  is  set  with  the  value  of  the  function 
key  pressed,  (cr  -1  if  the  INT  key  has 


. 
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been  pressed)  . 

(iii)  With  D ALPHA 

IX,  IY  are  set  with  the  screen  coordinates 
of  the  centre  of  the  first  character  of 
the  string. 

STRING  is  set  with  the  characters  input, 
two  to  each  half-word,  lef t-to-r ight . 

NUM  is  set  with  the  number  of  half-words 
of  STRING  used.  (The  actual  number  of 
characters  is  2*NUM  or  2*NUM-1;  all  unused 
elements  of  STRING  will  be  blanked) . 

MAX,  the  dimension  of  STFING,  is  supplied 
by  the  programmer  to  guard  against  a 
situation  in  which  the  operator  types  a 
string  of  characters  longer  than  the  space 
allowed  in  STRING. 

(iv)  With  DVECT  and  DFOINT 

Arrays  X,  Y  are  set  with  coordinates  of 
the  vector  end  points  (DVZCT) ,  or  points 
(PPOINT)  . 

NUM  is  set  with  the  number  of  points  in 
each  case,  i.e.  if  NUM=n,  then  there  are 
n-1  vectors  or  n  points. 

MAX,  the  dimension  of  X  and  Y,  is  supplied 
by  the  programmer.  X(NUM+1)  to  X(MAX)  and 
Y(NUM-H)  to  Y  (MAX)  will  be  set  to  zeros. 


i  X  -i=4: 
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3.2.7  Data  C 


on version 


(1)  and  (2)  are  function  subroutines. 


(3)  ,  (4)  and  (5)  are  subroutines  to  be  called. 


(1)  X  =  CHRFLT  (STRING,  LENGTH,  ERROR) 


Parameters  X:  Mode:  REAL  or  RE AL*8 


CHRFLT:  Mode:  Must  be  the  same  as  for  X 
STRING:  Mode:  Any  scalar,  array,  or 
literal  string. 

LENGTH:  Mode  INTEGER;  Range  1 <LENGTH< 1 6 
ERROR:  Mode:  LGGICAL*1 


Functio  n 


X  is  set  to  the  value  of  the  floating-point 
number  represented  by  the  string  of 
characters  beginning  at  the  left-most  byte  of 
STRING.  The  number  of  characters  is  specified 
by  LENGTH.  STRING  may  include  a  sign,  or  a 
decimal  point.  Absence  of  sign  implies  a 
positive  number.  If  there  is  no  decimal 
point,  it  is  assumed  to  follow  the  string. 
The  string  may  include  leading  blanks  (only) . 
ERROR  is  set  to  .TRUE,  (and  X  to  zero)  if  the 
string  contains  an  illegal  character,  or  if 
the  LENGTH  is  not  within  the  allowed  range. 


4 


' 
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(2) 


Otherwise,  ERROE  is  set  to  .FALSE. 


Examples : 


(i)  Z  (I)  =  CHRFLT  (P(J),8,L)  sets  Z  (I)  with 

the  value  of  the  number  expressed  in  8 
characters  beginning  with  the  left-most  byte 
of  P  (J)  . 

(ii)  Y=  CHRFLT  ('-124. 08  ', 7, A) 


I  =  INTCVT 

(STRING, 

LENGTH, 

ERRORS 

Parameters 

I: 

Mode  : 

INTEGER  or  INTEC-E 

R*2 

INTCVT: 

Mode : 

Must  be  the  same 

as  for  I 

STRING : 

Mode : 

Any  scalar,  array 

,  or 

literal 

string 

• 

LENGTH: 

Mode : 

INTEGER;  Range  1< 

LENGTHS  1 6 

ERROR : 

Mode : 

LOGI C A  L* 1 

Function 


I  is  set  to  the  value  of  the  integer  number 
represented  by  the  string  of  characters 
beginning  at  STRING.  STRING  may  include 
leading  blanks  (only) ,  a  sign,  but  no  decimal 
point.  Absence  of  sign  implies  a  positive 
number. 

LENGTH  and  ERROR  are  as  for  CHRFLT. 


Example  M=  INTCVT  (A(T),10,E)  is 


equivalent  to 
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reading  with  110  format. 


(3)  CALL  FLTCHR  JXxST RI NGXL ENGT H^DECSl 


parameters  X:  Mode:  REAL  or  R  EA1*  8 


STRING: 

Mode :  Any  scalar 

cr 

arr 

ay 

LENGTH: 

INTEGER 

variable 

or 

con 

stant 

DECS: 

INTEGER 

variable 

or 

con 

stant 

Range:  0<EECS<7 

Function^ 

Floating-point  number  X  is  converted  to  a 
character  string  of  length  LENGTH,  with  DECS 
characters  after  the  decimal  feint.  If  LENGTH 
is  not  sufficient,  the  string  is  filled  with 
*'s.  If  LENGTH  is  greater  than  needed, 
leading  blanks  will  be  inserted. 

Exam^le^: 


CALL 

FLTCHR  (X  ,  Z  ,  8 

r  2) 

will 

convert  the  value 

of  X 

to  a 

character 

str 

ing 

beginning  in  the 

left- 

most 

byte  of 

z. 

with 

format  conversion 

as  F8 . 2 . 

(4)  CALL  IN TC HR  STRINGX  LJX  L2j_ 

Parameters  J:  Mode:  INTEGER  or  INTEGER*2 

STRING:  Mode:  Any  scalar  cr  array. 


. 
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LI: 

Mode : 

INTEGER 

constant 

L2 : 

Mode  : 

INTEGER 

constant 

Function 

Integer  J  is  converted  to  a  character  string 
of  length  12,  beginning  at  the  left-most  byte 


of 

STRING.  If 

there  are 

more 

than 

characters,  STRING 

is  filled 

with 

*  »s. 

must 

show  the  mode 

of  J,  2  if 

J  is 

INTEGER 

4  if  J  is  INTEGE  E*4 . 

ExamjDle^ 

CALL  INTCHR  ( M  (I )  ,  P  ( J)  ,  2 , 8) 

specifies  that  M  (I)  ,  of  mode  INTEGERS,  is  to 
be  converted  to  an  8-character  string, 
beginning  at  the  first  byte  of  F  (J)  . 

(5)  CALL  CMP  HEX  JSTRINGJ[X  SI  RING  2X  LENGTH^ 


Parameters 

STRNG1  : 

Mode  : 

Any  scalar 

cr  array 

STRNG2: 

Mode : 

Any  scalar 

or  array 

LENGTH: 

Mode : 

INTEGER 

Function 

The  contents  of  core  storage  beginning  at 
STRNG1  is  converted  to  a  character  string 
beginning  at  STPNG2 ,  where  STRNG2  becomes  the 
character  equivalent  of  the  hexadecimal 


< 

■ 
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representation.  STFNG2  will  be  twice  the 
length  of  STRNG1.  LENGTH  specifies  the  number 
of  bytes  of  STRNG 1 . 

Ixamplej. 

CALL  EMPHEX  (A,E,128) 

specifies  that  128  bytes,  beginning  at  the 
leftmost  byte  of  A,  must  be  converted  to  a 
256  character  string,  beginning  at  the  left¬ 
most  byte  of  B. 

3.2.8  LO  GIC  AL*_1  Arguments 

A  useful  convention  is  to  give  a  declaration  such  as: 
LOGICAL* 1  A/. FALSE./, B/. TRUE./, BL/ . TFUE . / , NB/ . FALSE./, 

LG/. TRUE./, SM/. FALSE. /,D/. TRUE ./,ND/. FALSE. /,LFCN/. TRUE./, 
LPCFF/. FALSE ./ 

to  provide  convenient  mnemonics  for  those  options  to  be 
specified  by  logical  variables. 


A 

for 

"absolute" 

(relative 

to  block  origin) . 

R 

for 

"retative" 

(to  last 

beam  position) . 

BL 

for 

"blinking" . 

NE 

for 

"not  blinki 

ng  " . 

LG 

for 

"large"  cha 

r acters . 

SM 

for 

"small"  cha 

r acters . 

D 

for 

"dashed"  ve 

ct  or . 

ND 

for 

"not  dashed 

"  vector. 

l.  e 


' 
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LPON  for 
LPCFF  for 


•'light  pen  detectable”. 

"not  light  pen  detectable”. 


One  can  then,  for 
C A II  VECTOR  (A  or  R,  X 


example,  give  calls  such  as 
Y,  BL  or  NB ,  D  or  ND)  . 


• 

% 
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APPENDIX  II 

A  Sample  Program  Using  GRIDSUB 

C  THIS  PROGRAM  ALLOWS  THE  GRAPHICS  OPERATOR  TO  DISPLAY  UP 
C  TO  SEVEN  TRIANGLES  AND/CR  UP  TO  SEVEN  SQUARES.  THERE  ARE 
C  THREE  COMMANDS  ON  THE  SCREEN:  'DELETE' r  'TRIANGLE'  AND 
C  'SQUARE '  ,  TO  CREATE  A  SQUARE  CR  A  TRIANGLE,  HE  FIRST 
C  POINTS  TO  THE  RELEVANT  COMMAND  WORD,  THEN  CREATES  A  POINT 
C  CN  THE  CRT  TO  DENOTE  THE  DESIRED  POSITION,  AND  FINALLY 
C  PRESSES  THE  SEND  KEY.  HE  MAY  DELETE  ALL  THE  TRIANGLES 
C  (OR  SQUARES)  BY  FIRST  POINTING  TO  'DELETE*  AND  THEN  TO 
C  'TRIANGLE'  (CR  'SQUARE').  HE  ENDS  THE  PROGRAM  BY  PRESSING 
C  ANY  STATUS  KEY,  FOLLOWED  BY  ANY  FUNCTION  KEY, AND,  AS 
C  ALWAYS,  THE  SEND  KEY.  IF  THE  OPERATOR  ERRS,  A  MESSAGE  IS 
C  RETURNED:  'ERROR  TRY  AGAIN'. 

SUBROUTINE  GRAFIC 
IMPLICIT  INTEGER  (A-Z) 

INTEGER* 2  XX, YY 

LOGICAL*  1  T/.TRUE./,F/. FALSE./, FLAG/. FALSE./ 

INTEGER  ELK  (8) 

C  SET  UP  THE  THREE  COMMAND  WORDS 
CALL  ELOCK(I) 

CALL  TEXT  (F, 0,0, 6, 'DELETE', F,F) 

CALL  ENDELK 
CALL  BLOCK  (2) 

CALL  TEXT  (F, 0,0, 8, 'TRIANGLE' ,F,F) 


CALL  ENDELK 


r  '  ; 


•  • 


. 


96 


CALL  BLOCK  (3) 

CALL  TEXT  (F,0, 0,6,  ' SQUARE* ,F,F) 

CALL  ENDELK 

C  SET  UP  THE  ERROR  MESSAGE 
CALL  ELOCK  (4) 

CALL  TEXT  (F  r  0 , 0, 16, * ERROR- -TRY  AGAIN  * ,  T  ,  T) 

CALL  ENDELK 
C  CREATE  A  SQUARE 
CALL  BLOCK  (6) 

CALL  VECTOR (F, 200,0, F,F) 

CALL  VECTOR  (F , 200 , 200 , F , F) 

CALL  VECTOR (F , 0 , 200 r F , F) 

CALL  VECTOR (Fr0,0,F,F) 

CALL  ENDELK 
C  CREATE  A  TRIANGLE 
CALL  BLOCK  (5) 

CALL  VECTOR (F,200,0,F,F) 

CALL  VECTOR (F , 100,200,F,F) 

CALL  VECTOR  (F, 0, 0,F, F) 

CALL  ENDELK 

C  DISPLAY  THE  THREE  COMMAND  WCFDS 
CALL  DISPLY  (1  ,  1 ,5, 850) 

CALL  DISPLY  (2,1,5,900) 

CALL  D IS  ELY  (3 ,  1,5,950) 

C  INITIALIZE  ID'S  FOP  SQUARES  AND  TRIANGLES  TO  ZERO. 
SID  =  0 
TID  =  0 


C  SEND  DISPLAY  FILE  TO  THE  GRID  UNIT 


*: 


- 

■ 


■ 
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1  CALI  TRANMT 

C  WE  NOW  HAVE  A  MESSAGE  FROM  THE  CFERATOR 
C  TEST  WHETHER  THE  ERROR  MESSAGE  IS  TO  BE  DEIETED 
C  FFCM  THE  SCREEN 

IF  (.  NOT.  FLAG)  GO  TO  2 

C  THE  ERROR  MESSAGE  WAS  SENT  LAST  TIME,  WE  NOW  DELETE  IT. 
CALL  FRFEBK  (4) 

FL AG=  F 

C  SEE  IF  FIRST  OPERATOR  ACTION  WAS  A  FUNCTION  KEY 
C  DENOTING  END  OF  JOB 

2  CALL  EFKEY  (1 , STATUS, KEY, S4) 

C  SEE  IF  IT  WAS  A  LIGHT  PEN  HIT 

CALL  DLPEN  (1,X,Y,TYPE,ID,ELK,S5) 

C  IT  WAS  NOT  A  FUNCTION  KEY  OP  LIGHT  FEN — 

C  SIND  ERROR  MESSAGE  TO  GRID 

3  CALL  DISFLY  (4,  1  ,400,500) 

FL AG~T 

GO  TO  1 

C  CHECK  WHETHER  LIGHT  PEN  WAS  POINTED  TO  A  COMMAND 
C  IF  NOT  SEND  ERROR  MESSAGE 
5  IF  (BLK  (1  )  .  GT.  3)  GO  TO  3 
C  CHECK  WHETHER  IT  WAS  THE  DELETE  COMMAND 
IF  (BLK  (1 )  . GT. 1)  GO  TO  6 
C  SERVICE  THE  DELETE  COMMAND 

C  CHECK  IF  SECOND  ACTION  WAS  A  LIGHT  PEN  HIT 
C  IF  NOT  SFND  ERROR  MESSAGE 

CALL  DLPEN  (2,X,Y,TYFE,ID,EIK,S7) 


GO  TO  3 


81  I  '  . 

' 
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C  CHECK  IF  PEN  POINTED  10  'TRIANGLE '  OF  •SQUARE1 

7  IF  (BIK  (1)  .EQ. 3)  GC  TO  8 
IF  (BLK  (1  )  .  EQ.  2)  GO  TO  9 
GO  TO  3 

C  DELETE  ALL  THE  SQUARES 

8  CALL  EREEBK  (6) 

SID  =  0 

GO  TO  1 

C  DELETE  ALL  THE  TRIANGLES 

9  CALL  FREEBK  (5) 

TID  =  0 

GO  TO  1 

C  SERVICE  A  TRIANGLE  OR  SQUARE  COMMAND 

C  CHECK  IF  SECOND  ACTION  WAS  A  POINT — IF  NOT  SEND  ERROR 
6  CALL  EPOINT  (2,NUM,1rXXrYXrS10) 

GO  TO  3 

C  CHECK  WHETHER  SQUARE  OR  TRIANGLE  IS  TO  EE  AIDED 

10  X=XX 
Y  =  Y  Y 

IF  (BLK  (1  )  .  EQ.  3)  GO  TO  11 
C  ARE  THERE  ALREADY  SEVEN  TRIANGLES? 

IF  (TIE.GT. 6)  GO  TO  3 
C  INCREMENT  IE  FOR  TRIANGLES 
TIE=TIE+  1 

C  INSERT  ANOTHER  TRIANGLE 

CALL  EISFLY  (5,TID,X,Y) 

GO  TO  1 

C  ARE  THERE  ALREADY  SEVEN  SQUARES? 


r 


■ 


1 1  IF  (SIC.GT.  6)  GO  TO  3 
C  INCREMENT  IE  FOR  SQUARES 
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S I D=  S I E  +  1 

C  INSERT  ANOTHER  SQUARE 

CALL  DISPLY  (6rSIDrXrY) 

GO  TO  1 

C  ERASE  THE  CRT  AND  SEND  A  FAREWEIL  TO  INDICATE  END  OF  JOE 


a  CALL 

SNAP  (.  05) 

CALL 

EELELK  (1) 

CALL 

DELELK  (2) 

CALL 

DELELK  (3) 

CALL 

EELELK  (5) 

CALL 

DELELK  (6) 

CALL 

ELOCK  (7) 

CALL 

TEXT (Fr0,0,8, 'FAREWELL* ,T,T) 

CALL 

ENDELK 

CALL 

E IS  PL  Y (7 , 1  ,400,500) 

CALL 

TBANMT 

C  GIVE  CONTROL  EACK  TO  MASTER  CCNTFOL  ROUTINE 
RETURN 


END 


' 

Vt  '  A*  r  JJ  AD 
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APPENDIX  III 
OS  S  Calling  Sequence 


Program  Entr^ 
PRCGNAME  CSECT 


STM 

R14, R12, 12  (R13) 

LR 

R12, R15 

USING 

PROGNAME, R12 

LR 

E  10  ,  R 1  3 

LA 

R13, SAVEAREA 

ST 

RIO, 4  (R13) 

ST 

R  1 3 , 8  (RIO) 

B 

START 

SAVEAREA  DC 

00 

►n 

o 

Proqram  Exit 

EXIT  L 

R  1  3 , 4  (R  1  3) 

LM 

R14  ,R12, 12  (R 1 3) 

SR 

R  1  5  ,  R  1  5 

BR 

R  1  4 

SAVE  REGISTERS  FOR  RETURN 
ESTABLISH  BASE  REGISTER 
ESTABLISH  ADDRESSABILITY 
SAVE  OLD  SAVE  POINTER 
LOAD  SAVE  POINTER 
STORE  BACK  POINTER 
STORE  FORWARD  POINTER 
GO  TO  START  OF  ROUTINE 
SAVE  AREA  ALLOCATION 

LOAD  BACK  POINTER 
RELOAD  REGISTERS 
SET  ZERO  RETURN  CODE 
RETURN  TO  CALLER 
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_Sav  e  Area  Format 

WORD  CONTENTS 

1  Used  ty  PL/1  programs 

2  Address  of  previous  save  area  (stored  by 
calling  program) 

3  Address  of  next  save  area  (stored  by  current 
program) 

4  Register  14  (return  address) 

5  Register  15  (entry  point  address) 

6  Register  0 

7  Reqister  1  (parameter  list  address) 

8  Register  2 

9  Register  3 

10  Register  4 

11  Register  5 

12  Register  6 

13  Register  7 

14  Register  8 

15  Register  9 

16  Register  10 

17  Register  11 

18  Register  12 


Register  Conventions 
Register  1-  contains  the 
which  point  to  the  respective  parameters, 
in  the  list  has  the  high  order  tit  set  to  1 


ddress  of  a  list  of  addresses 


The  last  address 


‘ 


. 
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Regi s ter  1 

FOUR  BYTES 

N 

? 

00  ADDRESS  OF  PARAMETER  1 

00  ADDRESS  OF  PARAMETER  2 

•  • 

•  • 

•  • 

80  ADDRESS  OF  LAST  PARAMETER 

^~FULL  WORD  BOUNDARY 


Figure  I  I  1-1  Standard  Parameter  List  Convention 


Register  13  -  contains  the  address  of  the  save  area  used  in 
processing  requests  made  through  system  macros.  This  save 
area  is  also  used  to  store  the  current  programs  registers  if 
another  program  is  called. 

Register  14  -  contains  the  address  to  which  the  current 
program  is  to  return. 

Register  15  -  contains  the  entry  point  address  when  control 
is  passed  between  routines.  This  register  is  used  to  pass  a 


return  code  to  the  calling  program  when  return  is  made. 


:  I  ensJa  ijsi  emfiigonq  Jnsvtua  9ri1  eioJe  o  t  ‘  zu  o«  b 


103 


APPENDIX  IV 

Internal  Logic  Documentation 


F  ACTC  BIN 


a)  Purpose 

This  routine  converts  packed  format  data  to 
binary  format  data.  This  routine  does  not 
reference  any  other  routines. 

B)  Entry;  Point  -  BINTCF AC 

The  entry  point  BINTCPAC  converts  binary  format 
data  to  packed  format  data.  This  routine  does  not 
reference  any  other  routines. 

C)  Calling  Routines 

(I)  P  ACTOBIN 

TRANMT  calls  PACTCBIN  to  Unpack 
header  and  message  received  from  GRID. 


(II)  BINTOPAC 

TRANMT  calls  BINTOPAC  to  pack 
headers  and  messages  before  transmitting 
messages  to  GRID. 


D)  Calling  Sequence 

Both  PACTOBIN  and  BINTCPAC  use  standard  CS 
linkage  conventions  and  require  two  parameters 

E)  Parameters 

Parameter  1  -  full  vcrd  containing  the 
address  of  the  text  to  be  converted, 
address  must  be  halfword  aligned. 
Parameter  2  -  full  word  containing  the 


. 


length  in  bytes  of  the  text  to  be 
converted . 
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F)  Exit  Points 

Both  PACTOBIN  and  BINTOPAC  return  throuqh  the 
same  exit  point.  Return  cede  is  always  zero  as  no 
stock  is  made  on  the  validity  of  the  data. 

G)  Tables 

No  tables  are  referenced  by  either  routine. 

H )  Processing  Performed 

In  the  packed  format,  two  bytes  in  the  360 
transterred  through  the  interface  correspond  to  one 
core  memory  location.  For  packed  mode  transmission 
the  highest  order  bit  in  each  byte  must  be  1  to 
avoid  interface  interpretation  as  a  central 
character.  The  preparing  cf  data  for  transmission 
and  the  conversion  of  received  data  is  performed 
by  EINTOPAC  and  PACTOEIN  respectively. 

See  the  flowchart  and  following  diagrams. 


1C  ''.n.  >'£  3  »>r  J  I  * 


-- 
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PACTCB I N/B I NTOPAC 


FIT.  | V- 2  FLOWCHART  FOR  PACTCB I N/B I MTCPAC 


107 


o 

LU 

o 

cc 

o 

_J 

c 

Csl 

LU 

2 

i — 

1 — 

— J 

o 

LU 

LU  h- 

LU 

CO 

<L 

-J 

—  LU 

_ 

X 

O 

< 

X  LU 

X 

o 

-J 

CO  -J 

to 

o 

LU  U3 


LU  OQ 


—  3 
X  O 
CO  O 


o 

o 

o 

o 

o 

o 

o 

o 

o 

o 

o 

X 

o 

o 

X 

o 

X 

X 

• 

X 

• 

• 

X 

• 

• 

>- 

• 

• 

• 

>- 

• 

• 

>- 

• 

• 

>- 

o 

• 

>- 

o 

• 

• 

o 

X 

• 

• 

X 

• 

X 

CL 

X 

o 

O 

• 

X 

o 

o 

o 

X 

Cj. 

• 

X 

o 

o 

o 

X 

• 

X 

X 

X 

X 

to 

x 

X 

X 

X 

X 

X 

o 

X 

X 

X 

X 

X 

M. 

X 

X 

X 

X 

1 — 

X 

X 

X 

X 

X 

o 

CO 

rH 

o 

1 — 1 

X 

rH 

X 

r-i 

X 

rH 

X 

rH 

o 

c 

ro 

K\ 

tr\ 

H 


o 


tO 

Cu 

LU 


X 

cu 

-y. 


> 


cc 


o 

o 


C- 

< 

C  CM 


CM 

I — 

U_  J— 

—  Lu  O 

X  LU  O  CM 

CO  — I  <£ 


Q 
LU  Cu 
O  O 
<  3: 

-J  LU 
CU 

Lu  < 
CC  X 


o 

o 

o 

o 

X 

o 

o 

o 

o 

o 

X 

o 

rH 

rH 

X 

o 

rH 

X 

X 

o 

o 

X 

X 

X 

X 

X 

o 

o 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

o 

X 

X 

o 

X 

rH 

X 

X 

rH 

o 

o 

.o 

o 

X 

rH 

O 

rH 

rH 

X 

X 

O 

o 

X 

X 

• 

o 

o 

X 

X 

• 

• 

X 

X 

• 

X 

X 

o 

X 

• 

rH 

o 

• 

• 

• 

o 

!— 1 

• 

• 

• 

o 

• 

• 

• 

• 

• 

• 

• 

o 

o 

o 

o 

o 

o 

rH 

o 

rH 

o 

rH 

o 

rH 

o 

rH 

o 

rH 

o 

ro 

1 

r>o 

m 

hO 

hO 

ro 

FIGURE  IV-3  BINARY  TO  PACKED  FORMAT 


108 


O 

O 

LU  CL 

CN 

O  O 

h- 

<  2 

LL 

h- 

— 1  U- 

— 

LL 

0 - 1 

X 

LU 

LU 

to 

a:  x 

o 

o 

o 

o 

X 

X 

X 

X 

X 

• 

X 

>- 

• 

X 

Cl 

X 

< 

r—i 

• 

• 

X 

+ 

• 

• 

X 

• 

• 

X 

cc 

C 

• 

X 

c 

• 

o 

o 

e 

> 

• 

>- 

<u 

X 

X 

c: 

X 

LU 

L. 

X 

• 

(1/ 

o 

o 

X 

• 

o 

4-> 

>- 

>- 

X 

• 

<C 

4/) 

>- 

>- 

X 

a. 

>- 

X 

X 

>- 

>- 

X 

CL 

(D 

>- 

X 

X 

C 

£_ 

O 

X 

>- 

X 

o 

LL 

(/} 

H— 

H 

h- 

c_ 

LL 

LL 

LL 

u_ 

Ci 

LU 

CD 

LU 

LU 

CD 

J- 

CL 

-J 

_J 

00 

o 

Lu 

LU 

h- 

-J 

1 —  CM 

H- 

c 

LL 

LL 

CD 

LL 

LL 

cc 

o 

<1 

— 

X) 

— 

— 

X 

— 

o 

<5L 

ZL 

o 

X 

X 

o 

00 

00 

lD 

00 

oo 

CL 

LU 

> 

>- 

o 

X 

O 

o 

c. 

>- 

rH 

X 

rH 

rH 

o 

>- 

X 

X 

o 

o 

>- 

X 

X 

>- 

X 

X 

>- 

X 

X 

c 

o 

X 

o 

a; 

rH 

X 

rH 

> 

X 

o 

a) 

X 

f— 1 

X 

o 

X 

L. 

X 

• 

• 

QJ 

X 

• 

• 

4-» 

o 

• 

• 

CO 

rH 

o 

• 

w 

• 

<D 

• 

(X 

• 

• 

• 

o 

o 

o 

o 

x 

x 

x 

x 

x 

x 

x 

X 

X 

X 

X 

X 

o 


-Cf- 

I 

> 


LU 

c 

X 

o 


PACKFP  FORMAT  TP  BINARY 


PACT*U*In:  PACKfO  FT^MAT  TO  FINAQY 


LOC  tlHJfCT  CUDc  A0DR1  ADOR?  STMT  SOURCE  STATEMENT 


OJ  ~  n 

<  ip  ® 

K  ®  ©• 

N  <\ 

C 

2  § 

eg  <NJ  <M 

o  o  o 
©  o  o 
>  >  > 

eg  M  eg 
o  o  o 
o  o  o 
>  >  > 

UJ  -»  2 

z  z  z 

z  z  z 

O  C 

coo 

0  o  o 

<  fU  c 

a  m 

©  ©  © 

©  ©  © 

-  (V.  r. 


3  3  3 

c  o  o  o 

U  UJ  U  ID 


I 

c  -  «\j  n  it  w  o 

a  i  a  i  iff  ir  a 

«  m  x  k  \tr  <r  c 

rv  )<m  rvi  rn 


I 

-•  <nj!  n  + 
*n  m;»n  n 
o  olo  o 
O  OIO  o 
>  >!>  > 
z  z  z  z 
o  Olo  o 
©  u  ©  u 


lO  —  <M 


<t  »n  ® 

N  C  O 

3  3  3 

3  3  3 

3  3  3 

a  o  o 

o  o  o 

O  O  O 

UJ  UJ  UJ 

UJ  UJ  UJ 

UJ  ©  UJ 

C  -  01 

to  Ilj  7  u  « 

a  t:  a  tx  a  a 

—  cvj  ro  ♦  iP  <0 

TVV')  ^  "1 


ro  *  m 


3  3  3 

a  a  o 

ID  UJ  UJ 


n  «  if)  ; 
a  n  a 

N-  QD  O' 


—  r\j  r  <  if  o 
c  c  ©  o  c  o  c 

c  o  c  o  c  o  o 

c  c  o  o  c  c  © 

a  c  ©  r  p  o  o 

c  c  ©  c  c  ©  © 


N  X  C  <  Z  © 
©  O  O  O  C  © 
o  c  c  c  O  c 
©  o  o  e  o  r 
c  o  ©  o  c>  o 
©  o  o  o  c  © 


r  u>  u  : 
©  © 
O  ©  © 

c  ©  © 

COO 

c  c  © 


—  M'fO  *  *0 

♦  ♦  ♦  * 

o  o  o.o  o  o 
o  o  o'o  o  o 

>  >l>  >  > 

z  z  z  z  z 
O  c  O’O  o  o 
©  ©  ©  ©  ©  u 


a  o 
o  UJ 
it  a 

</>  ID 
o  V) 
ID  < 

a  a 

id  z 
>  </> 

<  ~ 

u)  j 


</) 
^  UJ 

<r 

M 

eg  in 

«*  •* 
a  or 

•  • 

*  m 

a  I 


N 


x 

h  a 

J 


5  o  ^ 

ui  •* 
m  >  a 

«"•<«» 

K  (fl  ®  ^  h  O 

•  •  ♦  •  ff  • 

°  ">  "  2  £  ft 

a  a  «  a  </>  ~ 


a 

UJ 

£ 

*-  o 
z  a 

222 

< 

UJ  B  K 

>  a  u 
<  3 

</)  u. 

O  Ui 

3§* 

-I  K  K 


< 

UJ 


to  <  fc 
©  J  * 


•*  <U  n  f#  IP  >c 


«  X 

—  o 

o  © 
o  c 
o  c 


VJ  y. 

U  *J 
C 

0*  - 

C  f  © 
r  ©  o 
o  c 
coo 
©  o 
©  o 


T  X 
-  o 

©  © 
©  C 

c  c  < 
<  r  r 

tr  -  o 

—  <*  C 


X  u 
r'  r 

c  c 
©  © 
o  o 
o  c 


K  CO 

♦  ♦ 

o  o 
o  o 
>  > 
z  z 

35 


I 


u 

M  »  o 
< 

< 

Id 

> 

<  ' 

"! 
k  ao  ©  | 

♦  f  f  l 


o 

O  ® 

o  © 
c  o 
o  © 


o  c 
o  n  o 

©  C 
©  © 


c  © 
u.  O 

N  © 
*  © 


b  c  r 
cor 
cor 
cor 


<X  W  ♦  8 
Ifl  «>  m  if) 

oio  o  o 
oio  o  o 
»  >  >  > 

©  u 


K  ®'  o*  o  — 
m  m  in  ©  <0 
o  o  o  o  o 
o  o  o  o  o 
>  >  >  >  > 


S8!8 


O  1 1 


£  282 


z  2  2 


«  — 


N  U.  O 

-  j  a 

5Z 

ID  UJ 

« k  <n  u  ‘ 

3  2a- 


ss 


«J  3 


i  i  a 
R  J  IA 


a  2  2 
i/i  u>  </> 


«  «  N 

a  a  a 


-y  (V  n  I 
IT  U)  m  i 


iP^^ajfrto  —  N|rn 
id  it  in  if)  /)  ®  <o 


o  <  c  L  o 
o  o  o  lc  o 
o  o  o  p  © 
coopc 
o  o  c 


o  r 


O  N  ®  t  O  W 
0  0  0—00 
O  o  o  o  o  o 
o  ©  o  O  o  o 
o  o  ©  o  ©  o 


o  c  o  o  r 

□  core 
c  c  c  o 

-  -  •)  o  \ 

^  r  *"  r  o 

X  t)  ©  <  X 

j*  ;  if  Ir  « 

o  <t  a.  U  o 

•C  C  ©  si  N 

©coco 

r  c  o  o  o 

r  c  o  r  ° 

o  o  o  o  o 


Z  \  X  -f  o 

o  ©  o  u-  o  o 

c  o  ©  p  o 

o  o  o  e  o 

o  o  o  ©  cvj  <u 

I  #  <*  #  IP  IP  fVJ 

UflCUCO- 

c  X  ®  «  ♦  ^ 

o  <  uj  rv.  o 

N  K  N  a  T 

c  c  °  r  o 

o  o  c  r> 

•  p  o  ©  c  o 

,  p  o  o  c  o 


<0  u> 
o  o 
o  o 
>  > 
z  z 
o  a 
©  © 


®  o 
'C  X)  ^ 
o  o  o 
o  o  O 
>  »  > 
z  z  z 
o  o  o 
©  ©  © 


g 

ID 

Z  If) 

-  o 

22 

*  o 

©  < 

<  o 

8  3 
UJ  fo 

Ss 

3 


II 

u  z 
a  a 
3 


I/) 

uj  k©  uj 
a  -  p*  a 
n 

a  . 

J  5* 
n  -  | 
a  f\j  kn 

t“.fi 


m  ♦  nr> 
a  a 


*  la  g  »- 
i  «j  p  ®  j 


K  ® 

©  X 


r  © 

o  © 
o  © 
o  o 
c  o 


o  — 

N  f*» 


. 


. 


■ 


CROSS-REFERENCE  PAGE 


i 

N 

N 


</> 

UJ 

u 

z 

UJ 

g 

UJ 

VL 

UJ 

g 


z 

u. 

u 

o 


z> 

to 

< 

> 


z 

UJ 


to 

o 


*  5 


> 

10 


«  n  In 

O'  UJ  * 


r»  fw  |fj  wm  ^  uT 
^  vC  U)  ;  tv 


ONOjOO- 

<  <J  K  (O  o  o 
O  O  O  (O  c  o 
o  o  O  O  o  o 

oo  5  1000 
o  o  o  to  c  o 


♦  «  «  r* 


to 

« 

a 

2  C 

5£ 

X 

UJ 


o  ~ 

or 


I* 


IN 


!S 


9  > 


m  n- 

N  9 


c  :>o  ®  ♦ 


n  un  o  a 

♦  «  N  U) 


®  N  o.  "9  ®  a 
♦  N  9  <  <5  O 


—  eg 

9  9  9  9 


IT  £  N  AT  O 
r  r  m  r*'  n 


j 

<  X  u  O  UJ  u. 

e  o  o  (c  c  c 

ooepe  o 

0  0  0)0  0  0 

c  o  o  p  ^  c 

o  c  o  to  o  c 


O': 


m  eg, 


9  — 

o>  ® 


n  #  — l 
c*  ©  ^  j 


>0  9  0 
CO  « 


<v  m  <v® 

®  ®  ®  ® 


M  >0  N|C 
O  O  ® 


eg  *  » i— 

«  IT  If)  I® 


—  n  ®  >o 
«  it  m  >o 


iT  f»*  N  -C 
IP  IT  UJ  IT 


-  <M  UJ  I® 
IP  IT  IT  [IT 


®^®CCp- 
<\i  iu  <m  eu  h  i" 


c  -  eg  n  9  if) 

r  -r  i  p  a 


cr 


«  kr 
o  o 
o  to 
o  o 
o  o 

•-P 


<M  n  *  IT  <  N 
I  ff  I  E  o  * 


«)  a> 

T 


C  0* 
o  o 
o  o 
o  o 
o  o 
o  o 


IE 

o  b 
c  o 
r  p 
o  r 

«  * 


®  c 
a  g 


I 

o 

U  i 
to  c  I 

to  ii 
<  to  I 

ca 

*0  j 

in  - 

>-  •  . 

z  9  ‘ 

L 

s  n 

IK  * 


<  — 

»-  o 

ifl  •• 

n 

5- 


fgvriv  if&»n  »T!»r 


113 


APPENDIX  V 


FILE  AND  TABLE  USAGE  UNDER  GRIDSUB 


A  proqrammer  using  the  GRIESUE  package  may  occasionally 
wish  to  knew  how  close  he  is  to  exceeding  the  limits  of  the 
system.  The  capacities  of  files,  and  of  tables  which  index 
these  files,  are  given  below: 

(1)  BLOCK  FILE  (40K  bytes) 

(2)  BANK  0  TABLE  -  1  entry 
BANK  1  TABLE  -  256  entries 
BANK  2  TABLE  -  256  entries 

(3)  DISPLAY  FILE  (SPACE  AVAILABLE  FCR  CODE 
IN  GRID  CODE) 


-  approx.  8000  GRID  words. 

(4)  MESAGE  -  400  bytes  (approx.  200  grid  words) 

(5)  QUEUE  -  100  entries  (50  if  entries  cause 
by  MOVEBK) 

(6)  BUFFERS  (2)  -  each  2048  bytes 


The  sizes  of  these  tables  may  be  changed  by  re¬ 
assembling  various  portions  of  the  GRIDSUB  system.  (See 
system  description)  The  Display  File  space  uses  virtually 
all  of  Banks  1  and  2  and  cannot  be  increased.  Bank  0  is 
currently  dedicated  to  the  supervisor  which  may  be  readily 
expanded. 


The  function  of  each  file  and  table 
ELOCK  FILE  -  storage  space  fer  GRID  code 

frem  Block  definitions. 


is  as  follows: 
resulting 


- 

:  j(d) 


. 
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EANK  TABLES  - 


DISPLAY  FILE 


MESAGE 


QUEUE 


EUEEERS 


describe  the  contents  of  the  banks, 
cne  entry  for  every  copy  of  a  Block  in 
tne  bank  and  one  or  mere  entries  describing 
the  supervisor. 

-  space  reserved  in  GRID  core  for  the 

user  *  s  display  cede  (virtually  all  of  Banks 
1  and  2)  . 

-  a  CSECT  into  which  the  message  from  GRID 
is  placed.  Both  this  CSECT  and  MESSAGE 

in  the  supervisor  must  be  changed  to  alter 
message  length. 

-  used  to  keep  track  of  changes  that  need  to  be 
made  to  the  current  display  file.  All  entries 
are  removed  each  time  TRANMT  is  called. 

If  a  call  to  a  display  modification 
routine  results  in  the  error  message  'Queue 
Full  ...  '  unpredictable  errors  may  result. 

If  this  error  occurs,  the  user  should  either: 

1.  Make  fewer  display  modification  calls 
before  calling  TRANMT. 

2.  Reassemble  the  GRIDSUB  module 
QUEUE  giving  it  more  space. 

to  store  code  that  is  to  be  sent  to  GRID. 

The  size  of  the  buffers  and  their  number 
should  not  be  changed.  If  Buffer  over-flow 
occurs,  use  more  calls  to  TRANMT  and  make 
fewer  additions  to  the  Display  File  between 
calls  to  TRANMT.  The  buffers  are  emptied 
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each  time  TRANMT  is  called. 

In  the  Block  File  entries  are  created  by  a  combination  of 


calls  to 

the  MOVE,  VECTOR,  FCINT, 

DLINE, 

TEXT, 

BLOCK, 

ENDBIK, 

and  IDY 

routines;  entries  are 

deleted 

by  the 

DELBLK 

routine . 

In  the 

Display  File  entries 

are  created 

by  the 

DISPLAY 

routine ; 

and  entries  are 

deleted 

by  the 

FREEBK , 

DELBLK , 

and  DELID 

routine. 

Comments  and  Suggestions  for  storage  economy: 

Most  economic  use  of  storage  can  be  achieved  if 

1.  Calls  of  the  same  type  can  be  grouped  together. 

2.  Eeam  movements  can  be  kept  snail. 

3.  If  the  Display  File  is  nearly  full,  and  there  are  some 
Elocks  in  the  Display  File  which  have  been  ’erased* 

(not  deleted) ,  use  the  call  FFEFEK  on  these  erased 
Blocks.  This  will  release  storage  in  DSFIII 

without  destroying  the  Block  definition  in  the  BLFILE. 
The  Block  can  be  displayed  again  with  a  CALI  DISPLY. 

4.  If  a  Blcck  is  finished  with,  make  sure  that  DELBLK, 
rather  than  ERSBK,  is  called. 


' 
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